promptkit/docs/roadmap/implementation.md

External Backend Catalogs Implementation Plan

Purpose

This document is the ordered implementation plan for the target state in external-backend-catalogs.md. It is written for a coding agent implementing one stage per prompt, in order. The feature roadmap owns the intended end state, compatibility policy, migration safety requirements, and non-goals; this document owns sequencing and concrete implementation decisions.

The work spans these three sibling repositories:

• /home/eric/Workspace/promptkit with module path gitea.maximumdirect.net/eric/promptkit;
• /home/eric/Workspace/promptkit-backend-openrouter with module path gitea.maximumdirect.net/eric/promptkit-backend-openrouter; and
• /home/eric/Workspace/promptkit-backend-rakestrawhome with module path gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome.

Cross-Stage Constraints

Apply these constraints throughout every stage:

• Read and follow each repository's AGENTS.md and contributor documentation before changing it. In Promptkit, always follow docs/development.md, docs/policy/architecture.md, docs/policy/documentation.md, and docs/policy/testing.md.
• Implement exactly one stage per prompt. Start a stage only after every prior stage's completion criteria are satisfied and committed. Preserve unrelated work in all three worktrees and commit only the stage's intended files.
• Keep Promptkit an importable Go library. Do not add a command, service, runtime catalog download, global registration, mutable registry, or public Promptkit catalog API.
• Keep BackendOpenRouter and BackendRakestrawHome, their exact values, and all current consumer construction and source-precedence behavior unchanged.
• Keep the external modules data-only. Their non-test package code may import only embed and io/fs; it must not import Promptkit, read environment variables, perform network calls, or expose mutable assets.
• Use no committed go.work, go.work.sum, vendor tree, or replace directive. Temporary local workspaces may be used only for exploratory development and must be disabled for acceptance. Every dependency and release check must succeed with GOWORK=off through ordinary module resolution.
• Keep all default tests deterministic, offline, and credential-free. Remote publication and module-resolution checks are release gates, not test-suite behavior.
• Treat copying the Promptkit-maintained catalog assets into the LGPL-3.0 external repositories as an intentional copyright-holder relicensing decision. Preserve source provenance and record that decision in both catalog READMEs; do not imply that an ordinary dependency extraction alone changes an asset's license.
• Update the canonical current-state documentation in the same commit that introduces or changes the behavior it describes. In particular, do not defer an implemented-package inventory or source-boundary update to a later stage merely because the feature has not reached runtime cutover.
• Treat catalog content and compatibility as high-risk data-integrity work. Test strict decoding, duplicates, source ownership, immutable copies, precedence, and exact pre-extraction parity at their narrowest owners; do not repeat the same malformed-input matrix through the public facade.
• Never include catalog file contents, extra-parameter values, environment values, or candidate secret values in new diagnostics. Errors may identify the catalog display name and repository-relative asset path.
• Do not publish or move a tag that already exists. If a planned external module tag exists locally or remotely, verify that it identifies the exact intended release commit; otherwise stop and report the conflict.
• Do not create a Promptkit release tag as part of these stages. The external modules must be released because Promptkit needs resolvable versions, but Promptkit release publication remains governed by docs/release.md after the feature is accepted.

Shared Catalog Asset Contract

Stages 2 through 6 must use this exact contract in both external modules and Promptkit's private adapter:

• The module root package is named openrouter or rakestrawhome, matching the backend. It exports only:

  const Root = "catalog"
  func FS() fs.FS
  

  FS returns the package's embedded filesystem as an fs.FS; callers cannot replace or mutate the embedded value. Both declarations require accurate GoDoc.

• The embedded tree contains catalog/backend.json and one or more profile files below catalog/profiles/. Directories are allowed below profiles; every nondirectory entry there must be a regular .yml file. No other file, symlink, or special entry is part of the embedded tree.

• backend.json is one strict JSON object with these required fields and no others:

  {
    "schema_version": 1,
    "id": "openrouter",
    "endpoint": "https://openrouter.ai/api/v1",
    "api_key_env": "OPENROUTER_API_KEY",
    "concurrency_limit": 16,
    "queue_capacity": 1024,
    "extra_params": null
  }
  

  The Rakestrawhome manifest changes id to rakestrawhome, endpoint to https://inference.ai.rakestrawhome.com/v1, api_key_env to RAKESTRAWHOME_INFERENCE_API_KEY, and concurrency_limit to 4; it keeps schema_version: 1, queue_capacity: 1024, and extra_params: null. extra_params may be a JSON object in later compatible catalog releases, but it remains null for the compatibility baseline.

• Schema version 1 requires an integer version, a nonblank ID, endpoint, and environment-variable name, a positive integer concurrency limit, a nonnegative integer queue capacity whose sum with the concurrency limit fits in int, and extra_params equal to null or an object. Promptkit also applies all existing endpoint, environment-name, reserved-field, and bounded JSON-value validation.

• OpenRouter owns every existing built-in profile except rakestrawhome-gemma-4-31b; Rakestrawhome owns exactly that profile at the initial release. Copy the YAML bytes without changing IDs or behavior.

• Each catalog is self-contained: every base_profile must resolve inside the same module. A locally resolved profile must select the manifest's backend ID. Raw catalog profiles must not provide endpoint, api_key_env, or a raw API key; connection and credential-source metadata comes from the manifest.

• Strict source decoding and the bounded JSON-value rules are the primary secret-safety controls. In addition, recursively reject case-insensitive catalog extra_params keys named api_key, apikey, authorization, credential, credentials, password, secret, token, or access_token. api_key_env is the sole permitted credential-related catalog field. Do not use value-pattern heuristics as a substitute for structural validation; retain Promptkit's repository credential scan as a separate acceptance check.

• Both external modules start at v1.0.0. The two-function/constant asset surface and manifest schema are intentionally stable; normal profile-data changes use later semantic versions according to each module's compatibility policy.

Stage 1: Freeze The Pre-Extraction Compatibility Baseline

Status: Complete

Repository

/home/eric/Workspace/promptkit

Objective

Record the complete current built-in catalog before any data is copied or any runtime assembly changes. This stage must leave Promptkit using its existing hard-coded backend definitions and embedded profile repository.

Implementation

1. Add testdata/builtin-catalog-v1.json as a reviewable, permanently frozen compatibility fixture. Represent both normalized backend definitions and every raw built-in profile. Include all fields whose zero, empty, nil, or explicit state affects behavior, including queue_capacity_set, base_profile, backend, endpoint, model, execution settings, api_key_env, api_key_required, and extra_params. Sort backends by ID and profiles by ID so diffs are deterministic.
2. Add a focused compatibility test under internal/profile/builtin that reads the fixture, obtains normalized built-ins from internal/backend.Registry, discovers every current embedded profile, and compares complete semantic values. Compare both directions so a missing or extra backend/profile fails. Reuse the package's existing asset discovery and profile repository rather than adding production enumeration APIs in this stage.
3. Do not provide an automatic golden-file update path. The snapshot describes the migration baseline and must change only by deliberate review of the fixture itself.

Tests And Validation

1. Run the focused internal/backend and internal/profile/builtin tests.
2. Run go test ./... and go test -race ./....
3. Inspect the fixture diff against the current YAML and backend constants, confirm that it contains no credential value, and run the Promptkit credential scan from the development guide.

Completion Criteria

• One deterministic fixture accounts for both current backends and every current raw built-in profile.
• The fixture test fails for added, removed, or semantically changed catalog data.
• Promptkit runtime construction and production code are unchanged.

Stage 2: Build And Release The OpenRouter Catalog Module

Status: Pending

Repository

/home/eric/Workspace/promptkit-backend-openrouter

Objective

Create the independently testable OpenRouter data module, publish its source commit, and release immutable tag v1.0.0 before Promptkit depends on it.

Implementation

1. Initialize go.mod with module path gitea.maximumdirect.net/eric/promptkit-backend-openrouter and Go version 1.25.5. Name the root package openrouter.
2. Add catalog/backend.json using the exact OpenRouter manifest from the shared contract. Copy every current OpenRouter-owned YAML asset from promptkit/internal/profile/builtin/assets/ into catalog/profiles/<provider>/ without editing its bytes. Record in the README that the Promptkit-maintained source assets are intentionally being distributed under this repository's LGPL-3.0 terms with authorization from their copyright holder, and identify Promptkit as their source provenance.
3. Add the private embedded filesystem and the exact Root/FS public surface. Embed only catalog, return the embedded filesystem by value behind fs.FS, and add package GoDoc explaining that the module supplies immutable Promptkit catalog assets rather than runtime provider behavior.
4. Replace the placeholder README with concise ownership, consumption, compatibility, and validation guidance. State that Promptkit owns parsing, runtime behavior, credentials, and consumer documentation; catalog releases own OpenRouter manifest/profile data. Document the roadmap's ID stability, additive profile, correction, deprecation/removal, and manifest-schema compatibility policy.
5. Add docs/release.md with a source-only semantic-tag procedure. Require a clean synchronized main, no workspace/replacement/vendor tree, complete validation, an annotated tag, publication of only the selected tag, remote tag verification, and resolution from a temporary module with GOWORK=off.
6. Add focused tests that use the exported FS and Root and verify the exact embedded layout, strict manifest shape and owner ID, at least one profile, unique trimmed profile IDs, backend selection equal to openrouter, no connection fields or raw API key in profiles, and no forbidden secret key in nested extra parameters. A test-only gopkg.in/yaml.v3 dependency is permitted for robust YAML-node inspection; confirm that the non-test root package's dependency graph remains standard-library-only.
7. Run go mod tidy, commit the module with a short plain-English message, push main, create annotated tag v1.0.0, push only that tag, and perform the documented remote and temporary-module resolution checks. Never use a local replacement to satisfy the resolution check.

Tests And Validation

• Run go test ./..., go test -race ./..., go vet ./..., and go build ./... with GOWORK=off.
• Require gofmt -l to report no tracked Go files and run git diff --check before committing.
• Confirm GOWORK=off go list -deps . contains no non-standard-library runtime package and scan tracked content for credentials.
• After publication, resolve gitea.maximumdirect.net/eric/promptkit-backend-openrouter@v1.0.0 from a temporary module and verify the returned version.

Completion Criteria

• The OpenRouter module contains its manifest and the complete copied profile set behind the exact immutable asset API.
• Its validation is offline and its runtime package is standard-library-only.
• main and annotated tag v1.0.0 are published and independently resolvable.

Stage 3: Build And Release The Rakestrawhome Catalog Module

Status: Pending

Repository

/home/eric/Workspace/promptkit-backend-rakestrawhome

Objective

Create and publish the matching Rakestrawhome data module without coupling its release history or package implementation to the OpenRouter module.

Implementation

1. Repeat the module, package, immutable asset API, package documentation, README policy, and docs/release.md structure from Stage 2, using module path gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome, package name rakestrawhome, and Go version 1.25.5.
2. Add the exact Rakestrawhome manifest from the shared contract. Copy only google/rakestrawhome-gemma-4-31b.yml into catalog/profiles/google/, without editing its bytes. Apply the same explicit LGPL-3.0 relicensing and Promptkit source-provenance statement as Stage 2.
3. Apply the same focused asset tests, changing the expected backend to rakestrawhome and the initial profile set to the single owned profile. Keep the module independent: do not import or share code with either Promptkit or the OpenRouter module.
4. Run the same validation and release sequence as Stage 2, commit and push main, publish annotated tag v1.0.0, and verify ordinary module resolution without a workspace or replacement.

Tests And Validation

Use the complete Stage 2 validation list with the Rakestrawhome module path. Inspect the copied profile against Promptkit's Stage 1 fixture before release.

Completion Criteria

• The Rakestrawhome module contains exactly its owned backend and profile data behind the same stable asset contract.
• Its tests, build, runtime dependency check, credential scan, and remote resolution all pass.
• main and annotated tag v1.0.0 are published and independently resolvable.

Stage 4: Add Eager Immutable Profile Loading To Promptkit

Status: Pending

Repository

/home/eric/Workspace/promptkit

Objective

Add the reusable profile-package primitive needed to validate an immutable external catalog completely at engine construction, without changing the lazy point-in-time semantics of consumer-configured profile sources.

Implementation

1. In internal/profile, add:

   type LoadedProfileMetadata struct {
       ID             string
       Path           string
       ExplicitFields []string
   }
   
   func LoadFSRepository(
       ctx context.Context,
       fsys fs.FS,
       root string,
   ) (Repository, []LoadedProfileMetadata, error)
   

   It must discover sorted YAML paths through internal/filecatalog, read each file once, require exactly one document, strictly decode the existing profile schema, reject raw API keys, normalize and validate each raw definition through the existing owners, and reject duplicate trimmed IDs. Return an immutable in-memory raw repository plus a newly allocated metadata slice sorted by normalized profile ID. Each metadata entry contains that ID, the safe root-relative source path, and a newly allocated sorted list of the exact top-level YAML field names present in the source document. An empty source returns an empty repository and metadata slice; the catalog adapter, not this generic primitive, decides whether emptiness is invalid. All three fields, the type, and the function are internal to the Promptkit module but require accurate GoDoc because they cross internal package boundaries.

2. Refactor existing private decode/metadata logic only as needed so eager and point lookup share strict decoding, source-path context, raw-key rejection, normalization, and defensive JSON-value copying. Do not change NewFSRepository: configured and fallback consumer sources must retain fresh point-in-time reads and their current error-preserving fallback semantics. Derive ExplicitFields during the same source read and through the existing YAML-node metadata path; do not make the later catalog adapter reread or independently parse profile YAML.

3. The returned repository must honor context cancellation before lookup, return ErrProfileNotFound for absence, and publish a fresh profile value with a deeply copied ExtraParams tree on every successful lookup. Do not pre-resolve base_profile; the raw repository must remain suitable for the existing outer resolving repository and consumer shadowing rules.

4. Update docs/internal/sources.md in the same commit to describe the eager immutable loader as an implemented internal profile boundary. Make clear that configured consumer sources remain lazy and that engine assembly still uses the existing embedded built-ins at this stage.

Tests And Validation

1. Add focused profile-package tests for sorted metadata, exact explicit-field presence including explicitly empty values, safe relative paths, strict malformed-input rejection, duplicate IDs, raw API-key rejection, empty input, cancellation, and defensive copies of metadata and profile values. Reuse representative existing fixtures and avoid repeating the entire profile rule matrix already owned by point lookup.
2. Add a parity test showing that eager and ordinary FS repositories publish the same raw semantic value for representative standalone and derived profiles.
3. Run go test ./internal/profile, go test -race ./internal/profile, and go test ./....

Completion Criteria

• Promptkit can eagerly load and validate all raw profiles from an fs.FS without creating a second YAML contract implementation.
• Returned metadata and profile values are caller-independent, and the metadata preserves the distinction between an absent field and an explicitly empty field.
• Existing configured, fallback, in-memory, and built-in runtime behavior is unchanged.
• The internal source document accurately distinguishes eager immutable loads from existing point-in-time consumer source lookup.

Stage 5: Add And Verify The Private Catalog Adapter

Status: Pending

Repository

/home/eric/Workspace/promptkit

Objective

Import the two published module versions and validate them through one private Promptkit adapter while retaining the existing embedded/hard-coded runtime source as the active implementation.

Implementation

1. Add direct requirements at v1.0.0 for both external module paths and run go mod tidy with GOWORK=off. Do not add a replacement or workspace.

2. Add internal/catalog with this internal contract:

   type Source struct {
       Name              string
       ExpectedBackendID string
       FS                fs.FS
       Root              string
   }
   
   type Set struct {
       Backends []domain.Backend
       Profiles profile.Repository
   }
   
   func Load(sources ...Source) (Set, error)
   

   Name is a safe maintainer-facing label used in errors; reject blank or duplicate names. Require nonnil filesystems, valid non-root asset roots, nonblank expected IDs, and at least one source. Return caller-independent backend values and one raw immutable composite profile repository.

3. Strictly enforce the shared asset layout and manifest schema. Use json.Decoder.DisallowUnknownFields, require exactly one JSON value, use presence-aware raw fields so missing required fields differ from zero or null, reject unsupported schema versions, and check the manifest ID against ExpectedBackendID. When constructing domain.Backend, set QueueCapacitySet to true because schema version 1 requires an explicit queue_capacity; this ensures normalization preserves later compatible releases that intentionally select a non-default capacity.

4. Rename the existing private backend normalizer to the internal exported backend.NormalizeDefinition and have both Registry and the catalog adapter call it. This remains inside Go's internal boundary and is not a Promptkit public API. Do not duplicate endpoint, environment-name, capacity, reserved-field, or bounded JSON-value policy in the adapter.

5. For each source, call profile.LoadFSRepository on <root>/profiles. Reject an empty profile set. Use the returned explicit-field metadata to reject endpoint or api_key_env whenever the key is present, including when its YAML value is explicitly empty; do not infer source presence from the decoded profile's zero values. Validate every raw profile's nested extra parameters for forbidden secret keys. Resolve every metadata ID through a source-local profile.NewResolvingRepository; this both proves inheritance is self-contained and verifies that the final backend ID equals the manifest owner.

6. Reject duplicate backend IDs and duplicate raw profile IDs across sources. Compose the already validated raw repositories in source order only after duplicate checks pass. Do not pre-resolve the returned composite: the root engine must later place consumer sources above it and apply one outer resolver to preserve base-profile shadowing semantics.

7. Keep errors bounded and redacted. Wrap failures with the safe source name and relative path where available, but never include raw JSON/YAML values or extra-parameter content.

8. Add an integration test that imports the released openrouter and rakestrawhome packages, supplies their FS()/Root values with expected backend IDs, loads the set, and compares it exactly with testdata/builtin-catalog-v1.json. Keep the Stage 1 test against the old source too; at this point both tests must pass while only the old source participates in engine construction.

9. Update docs/policy/architecture.md, docs/internal/overview.md, and docs/internal/sources.md in the same commit. Describe internal/catalog as an implemented private validation/adapter boundary and the external modules as imported immutable test-verified sources, while stating accurately that root engine assembly still uses the original built-in runtime source until cutover.

Tests And Validation

1. At internal/catalog, use testing/fstest.MapFS tables for nil/invalid sources, layout violations, strict/trailing/missing/unsupported manifests, backend normalization failures, empty profiles, malformed profiles, cross-source duplicates, missing/cyclic/cross-catalog bases, owner mismatch, prohibited connection fields, secret-like nested keys, defensive copies, and redacted source-aware errors.
2. Keep exhaustive YAML rules in internal/profile and backend invariants in internal/backend; adapter tests must prove delegation and assembly, not duplicate those packages' full matrices.
3. Run focused tests for internal/profile, internal/backend, and internal/catalog, followed by go test ./..., go test -race ./..., go vet ./..., and go build ./....
4. With GOWORK=off, verify go list -m all selects exactly v1.0.0 for both catalogs and go mod verify succeeds.

Completion Criteria

• Both released external catalogs load through one strict private adapter and exactly match the frozen baseline.
• Every maintained profile is eagerly validated locally and across the assembled set before publication.
• Promptkit still executes exclusively from its original built-in data source.
• The current-state architecture and internal inventory describe this transitional implemented boundary without claiming that cutover is complete.

Stage 6: Cut Promptkit Over To The External Catalogs

Status: Pending

Repository

/home/eric/Workspace/promptkit

Objective

Make the validated external modules Promptkit's sole runtime owners for the maintained backends and profiles, then remove every duplicate production copy from Promptkit in the same committed cutover.

Implementation

1. In root engine assembly, import the two external packages with unambiguous aliases and construct catalog.Source values in deterministic OpenRouter, Rakestrawhome order. Use safe display names plus backend.OpenRouterID/backend.RakestrawHomeID as the expected IDs.
2. Load the maintained catalog.Set during NewEngine after options and the required prompt source have been validated, but before constructing the backend registry, capacity manager, or runner. Map any load failure to ErrInvalidConfig with the prefix failed to load maintained catalogs and preserve redacted catalog/path context. Add no new public error identity.
3. Change backend.NewRegistry to accept maintained definitions and consumer additions as separate slices. Normalize and copy both through the same path, insert maintained definitions first, and reject every duplicate across or within the two groups. This preserves the rule that a consumer cannot replace a maintained ID without retaining hard-coded maintained definitions inside the registry package.
4. Change newProfileRepository to accept the maintained raw repository as its lowest-precedence source. Preserve this exact overlay order: in-memory, ordinary configured file/FS/directory, application fallback, maintained external catalog. Continue to wrap the complete raw overlay in exactly one profile.NewResolvingRepository.
5. Delete internal/profile/builtin, including its embedded YAML assets, and delete builtInBackends plus the OpenRouter/Rakestrawhome endpoint, environment, and concurrency constants from internal/backend. Retain the internal backend ID constants because the root public constants still alias them, and retain the generic default queue-capacity policy used for consumer registrations.
6. Move the Stage 1 compatibility assertion to internal/catalog and make it compare only the external loaded set to the frozen fixture. Remove tests whose sole purpose was the deleted duplicate source; retain or relocate distinct compatibility, reserved-ID, profile completeness, and native Rakestrawhome behavior coverage.
7. Update registry and engine tests for explicit maintained definitions. Add only focused assembled-engine coverage needed to prove that ordinary construction includes both catalogs, consumer backend IDs cannot replace either maintained ID, consumer profiles still override catalog profiles, inherited base lookup still observes the complete precedence chain, and capacity/credential/endpoint behavior matches the compatibility fixture. Reuse existing public contract tests wherever they already protect these outcomes.
8. Confirm with repository search and go list -deps that no production Go file embeds the old assets or hard-codes the extracted endpoints, environment-variable names, concurrency values, or profile model catalog. The frozen test fixture and canonical consumer documentation are the only permitted Promptkit copies of compatibility data.
9. Update docs/policy/architecture.md, docs/internal/overview.md, and docs/internal/sources.md in the cutover commit: remove the transitional old-runtime description, remove internal/profile/builtin, and describe explicit root assembly plus eager maintained-catalog validation and the unchanged outer consumer overlay/resolution boundary.
10. Update docs/formats.md where its current wording says the catalog is embedded or hard-coded. It remains the canonical consumer owner of the built-ins supplied by a Promptkit release, so retain the exact backend and profile tables after confirming them against the compatibility fixture. Do not duplicate pinned module versions there; go.mod owns them.

Tests And Validation

• Run focused backend, catalog, profile, root engine, capacity, and public contract tests.
• Run the complete Promptkit maintainer workflow from docs/development.md, including ordinary/race tests, vet, build, both offline examples, Go formatting, Markdown links, workspace/replacement/vendor guards, whitespace checks, ignored-file review, credential scan, and full diff/status inspection.
• Run the complete workflow with GOWORK=off and no provider credentials.

Completion Criteria

• Every new engine validates and uses both external catalogs automatically.
• Public constants, effective backend/profile values, source precedence, inheritance, capacity, credentials, and consumer additions match the frozen baseline and existing contracts.
• Promptkit has one runtime data owner: no embedded profile catalog or hard-coded extracted backend definition remains.

Stage 7: Update Current-State And Release Documentation

Status: Pending

Repository

/home/eric/Workspace/promptkit

Objective

Make durable documentation describe the implemented dependency boundary, provide concise consumer-facing release guidance, and perform final acceptance across all three clean repositories.

Implementation

1. Review the current-state changes made in Stages 4 through 6 against the final implementation. Correct any stale transitional language and ensure docs/policy/architecture.md, docs/internal/overview.md, docs/internal/sources.md, and docs/formats.md link to canonical owners instead of duplicating the manifest or complete catalog.
2. Update docs/development.md with a task-specific reading-guide row for external catalog or maintained built-in changes. Route contributors to the internal source document, the format reference, testing policy, both module repositories, and each module's release procedure.
3. Do not add a versionless supplemental release document during feature implementation. Record for the later Promptkit release-preparation pass that its versioned docs/releases/vMAJOR.MINOR.PATCH.md document should state that the release adds two independently versioned data dependencies, preserves the public API and configuration, requires no consumer migration, and guarantees only the catalog versions selected and tested by that Promptkit release. That document must link to canonical current-state documentation rather than restating its contracts.
4. Update each external repository README only if the final implemented paths or links changed during integration. Do not turn either README into a parallel Promptkit consumer manual.
5. Mark every stage in this plan complete only after its committed state and validation evidence exist. Leave Promptkit release tagging to the normal release procedure; the future annotated Promptkit tag message must include the dependency-boundary summary and the absence of consumer migration.

Tests And Validation

1. Run the full Promptkit maintainer workflow, including the local Markdown link validator, with GOWORK=off.
2. In each external module, run its full test/race/vet/build, formatting, hygiene, credential, and ordinary module-resolution checks.
3. From a temporary module, download both external v1.0.0 versions and the current Promptkit commit's module dependencies without a workspace or replacement. Promptkit itself need not be tagged in this stage.
4. Inspect all three worktrees and their committed diffs. Require each to be clean and confirm that Promptkit's go.mod/go.sum identify the published catalog versions.

Completion Criteria

• Durable current-state documents accurately describe the external asset boundary without duplicating implementation-plan detail.
• The later versioned release-document requirements are explicit without creating a release note before a Promptkit version has been selected.
• All completion criteria in the feature roadmap hold, all three repositories are clean, and the complete offline validation passes without credentials, a workspace, a replacement, or provider network access.

Open Questions

None. The implementation decisions required by this roadmap are fixed above.