notarius/docs/roadmap/implementation.md

PromptKit Dependency Migration Implementation Plan

Status

In progress. The dependency, framework adapter, version 4 PromptKit configuration migration, provider-neutral module prompt-asset support, provenance alignment, and canonical documentation are implemented; final repository verification is still planned.

Objective

Replace Notarius's dependency on gitea.maximumdirect.net/eric/scriptorium v0.11.1 with gitea.maximumdirect.net/eric/promptkit v0.1.0, and consistently adopt the PromptKit name at the adapter, configuration, provenance, documentation, and module-support boundaries.

The migration is a clean break. Notarius has no production compatibility requirement for the existing Scriptorium-named configuration or development artifacts, so the implementation must not add legacy configuration aliases, deprecated Go APIs, schema migrations, or compatibility shims.

PromptKit's public engine contract is source-compatible with the subset Notarius currently consumes. Preserve current prompt content, prompt and schema identities, structured-completion behavior, LLM scheduling, retry behavior, debug capture, redaction, and durable output shapes except for the intentional configuration-version and LLM-provider provenance changes described below.

Governing Decisions

• Pin PromptKit at v0.1.0 and remove Scriptorium from go.mod and go.sum.
• Rename the top-level configuration section from scriptorium to promptkit.
• Bump the strict file-configuration version from 3 to 4. Version 4 accepts only the new promptkit key; it does not recognize scriptorium.
• Rename the internal adapter and its exported-within-internal Go API to PromptKit terminology without transitional aliases.
• Use provider-neutral names for module-owned prompt asset helpers. Those helpers describe Notarius assets rather than the library that loads them.
• Record promptkit, not scriptorium, as the LLM adapter/provider value in completion responses and run manifest profile provenance.
• Do not add the PromptKit package version to checkpoint identity. A library implementation version is not itself a semantic pipeline input. Existing prompt, schema, module, reference, profile, runtime-override, and prepared component fingerprints remain responsible for semantic invalidation.
• Do not adopt PromptKit's optional ArtifactReader extension in this work. Notarius retains ownership of materializing and supplying prompt inputs.
• Do not add native session propagation in this work. PromptKit v0.1.0 does not expose the desired request-level session identifier; retain the existing prompt-variable behavior and update the future roadmap terminology only.
• Accept PromptKit's documented timeout layering: caller context cancellation is the outer authority, a positive generation timeout supplies an inner request deadline, zero disables only that generation deadline, and the HTTP client timeout remains a transport-wide cap.
• PromptKit and Notarius are both GPL-3.0 licensed, so the dependency change requires no Notarius licensing change.

Non-Goals

• Changing prompt text, message ordering, prompt IDs, schema IDs, or embedded asset paths.
• Changing public artifact schemas, output bundle contents, run-result receipts, checkpoint formats, or filesystem layouts.
• Adding new LLM profiles, changing profile precedence, or changing credential handling.
• Refactoring the transport-neutral StructuredLLMClient contract.
• Adding PromptKit features that Notarius does not currently need.
• Preserving version 3 configuration compatibility.

Stage 1: Replace the Dependency and Adapter

Update the Go dependency and the framework adapter as one compilable change.

Implementation

• Replace the Scriptorium requirement with gitea.maximumdirect.net/eric/promptkit v0.1.0, then run go mod tidy so go.mod and go.sum contain no obsolete Scriptorium module entries.
• In internal/framework/llm, replace imports of gitea.maximumdirect.net/eric/scriptorium with PromptKit and rename:
  • scriptorium_client.go to promptkit_client.go;
  • ScriptoriumClientConfig to PromptKitClientConfig;
  • ScriptoriumClient to PromptKitClient;
  • NewScriptoriumClient to NewPromptKitClient;
  • AssetRegistry.ScriptoriumOptions to AssetRegistry.PromptKitOptions; and
  • Scriptorium-named private input, variable, metadata, debug, response, validation, and error-redaction helpers to PromptKit terminology.
• Do not retain aliases for the old types, constructor, method, filenames, or private helpers.
• Preserve the existing adapter sequence:
  1. validate the transport-neutral request and output target;
  2. map inputs, variables, metadata, prompt identity, profile identity, and session prompt variable into a PromptKit RunRequest;
  3. call Prepare to capture rendered debug material;
  4. call Run;
  5. translate PromptKit validation failure into contracts.ErrInvalidStructuredOutput;
  6. decode the structured artifact into the caller's target; and
  7. return transport-neutral response, usage, profile, and debug data.
• Continue wrapping and redacting upstream errors at the same trust boundary. Update safe wrapper text from Scriptorium to PromptKit without exposing prompt content, credentials, artifact content, filesystem paths, or raw upstream payloads.
• Rename the adapter provenance constant and change its value from scriptorium to promptkit.
• Preserve PromptKit's cancellation and timeout semantics. Do not introduce another timeout wrapper in Notarius.
• Update the production composition root in internal/cli/catalog.go to construct PromptKitClientConfig and NewPromptKitClient.

Tests

• Rename and adapt the existing adapter and asset-registry tests; do not add tests whose only purpose is to enforce private symbol or filename choices.
• Through the adapter's stable behavior, retain coverage for:
  • engine and asset construction failures;
  • prompt, schema, input, variable, metadata, and profile forwarding;
  • structured-output success and validation failure;
  • malformed or empty generated output;
  • caller cancellation and configured timeout behavior;
  • credential and content redaction;
  • raw response and prepared-prompt debug capture;
  • token usage, including cached and cache-write token fields; and
  • profile manifest recording.
• Use injected PromptKit clients or local deterministic HTTP test servers. Default tests must remain offline and must not require credentials or paid model calls.

Completion Criteria

• The framework and production CLI compile against PromptKit only.
• No Go import of the Scriptorium module remains.
• Existing adapter behavior is preserved except that response and manifest provenance now identify promptkit.

Stage 2: Introduce Version 4 PromptKit Configuration

Make the user-visible configuration terminology agree with the dependency and adapter.

Implementation

• Change SupportedFileConfigVersion from 3 to 4.

• In internal/core/config, rename:

  • ScriptoriumConfig to PromptKitConfig;
  • FileScriptoriumConfig to FilePromptKitConfig;
  • Config.Scriptorium to Config.PromptKit;
  • FileConfig.Scriptorium to FileConfig.PromptKit; and
  • Scriptorium-named validation and application helpers to PromptKit terminology.

• Change the runtime JSON and file YAML section name from scriptorium to promptkit.

• Preserve the two optional fields and their meaning:

  version: 4
  promptkit:
    profile_dir: /path/to/profiles
    # profile_file: /path/to/profiles.yml
  

• Preserve trimming, clone, apply, effective-configuration, and redaction behavior for profile_dir and profile_file.

• Preserve the rule that profile_dir and profile_file are mutually exclusive and that an explicitly supplied value must not be empty.

• Update production client construction and explicit-profile validation to read cfg.PromptKit.

• Rename internal/cli/scriptorium_profiles.go and its functions to PromptKit terminology. Preserve the existing profile validation timing and errors.Is-based handling of PromptKit's ErrProfileNotFound.

• Keep YAML decoding strict. A version 4 file containing scriptorium must fail as an unknown field.

• Add a targeted version 3 migration diagnostic that instructs users to:

  1. change version: 3 to version: 4; and
  2. rename scriptorium: to promptkit:. Do not attempt to decode or automatically rewrite version 3 files.

• Update maintained configuration examples to version 4 and use promptkit wherever profile sources are demonstrated.

Tests

• Update configuration contract tests to establish:
  • a minimal version 4 file applies over defaults;
  • explicit PromptKit profile directory and profile file values decode and survive apply, clone, and effective configuration;
  • the two profile sources remain mutually exclusive;
  • explicit empty values remain invalid;
  • unknown fields remain rejected by strict decoding;
  • version 4 rejects the removed scriptorium key; and
  • version 3 produces the actionable migration classification.
• Update CLI contract tests to demonstrate that configured and explicitly selected PromptKit profiles are validated before pipeline preparation and that invalid profiles retain the existing process-failure behavior.
• Test configuration behavior at the parser/configuration and CLI composition boundaries. Do not reproduce PromptKit's own profile parser test matrix.

Completion Criteria

• All runtime and file configuration code uses PromptKit terminology.
• Maintained examples are valid version 4 files.
• The obsolete section is rejected rather than silently accepted or ignored.

Stage 3: Make Module Prompt-Asset Support Provider-Neutral

Remove dependency-brand terminology from module-owned prompt asset registration without changing the assets themselves.

Implementation

• Across the D&D scene chunker, extractors, NPC normalizer, and registration support, rename each scriptorium_assets.go and corresponding test file to prompt_assets.go and prompt_assets_test.go.
• Rename private helpers and values such as scriptoriumPromptRoot, scriptoriumPromptMetadata, and equivalent schema registration names to provider-neutral forms such as promptAssetRoot and promptAssetMetadata.
• Retain PromptKit terminology only where code directly calls a PromptKit API, such as producing promptkit.Option values at the framework asset registry boundary.
• Do not change:
  • prompt or schema contents;
  • prompt, schema, or asset IDs and versions;
  • embedded filesystem paths;
  • message ordering or cache-control placement;
  • module keys or declared prompt inputs;
  • metadata values or content fingerprint algorithms; or
  • extraction, normalization, or validation behavior.

Tests

• Update existing module prompt-preparation and registration tests to compile through the renamed support code.
• Retain the centralized behavioral coverage that all registered production prompts and schemas can be mounted and prepared with their declared inputs.
• Retain prompt ordering and cache-prefix contract coverage where ordering is semantically significant.
• Do not add word-presence tests, rename detectors, or private-helper tests.

Completion Criteria

• Module-owned code no longer describes its prompt assets as Scriptorium assets.
• Prompt and schema fingerprints remain unchanged from the pre-migration source content.

Stage 4: Align Provenance and Checkpoint Behavior

Make the intentional public provenance change explicit while leaving cache identity tied to semantic inputs.

Implementation

• Record Provider: "promptkit" in every newly observed LLMProfileManifest and StructuredCompletionResponse produced by the production adapter.
• Update manifest, debug, artifact, and assembled-run expectations that currently identify Scriptorium.
• Do not change checkpoint schemas, layouts, or the CheckpointFingerprintProvider contract.
• Do not introduce a fingerprint containing the PromptKit package name or version. Dependency implementation identity is not a stable semantic identity.
• Verify that no accidental prompt, schema, component, reference, profile, or runtime-override fingerprint changes result from the provider-neutral file and helper renames.
• If an existing test fixture contains recorded LLM provenance, update only the adapter/provider value and preserve the profile ID, model, usage, and remaining run data.

Tests

• At the adapter boundary, assert that a successful completion and recorded profile manifest report promptkit.
• At one assembled run boundary, confirm that the finalized manifest carries the PromptKit profile provenance observed by the client.
• Retain existing checkpoint identity tests for semantic prompt, module, profile, reference, and runtime changes. Do not add a test coupled only to the absence of a dependency-version fingerprint.

Completion Criteria

• New durable and debug provenance consistently identifies PromptKit.
• No checkpoint wire-format or layout change has been introduced.

Stage 5: Update Canonical Documentation

Update documentation in the same change that implements the behavior, following the repository's canonical ownership rules.

Implementation

• Update docs/config.md to own:
  • configuration version 4;
  • the promptkit section and its fields;
  • mutual exclusion and validation rules; and
  • the version 3-to-4 migration instruction.
• Update docs/operations.md to describe provider retries and timeouts as PromptKit profile behavior and accurately summarize the timeout layers.
• Update docs/internal/llm.md to describe:
  • the PromptKit-backed adapter;
  • transport-neutral request and response mapping;
  • asset mounting;
  • preparation, execution, validation, redaction, and debug behavior;
  • profile provenance; and
  • caller, generation, and transport timeout ownership.
• Update docs/internal/cli.md to describe PromptKit profile validation and production client composition.
• Update docs/development.md so its task-reading guide refers to the PromptKit integration.
• Update any maintained examples and nearby navigation links. Configuration definitions and defaults remain canonical in docs/config.md; other documents should summarize and link rather than repeat them.
• Replace the copied docs/integrations/pkg-promptkit.md guide with a concise Notarius-owned upstream boundary document. It must:
  • identify the pinned PromptKit package and supported public boundary used by Notarius;
  • link to PromptKit's canonical upstream package and format documentation;
  • describe only integration facts that Notarius relies upon;
  • point to docs/internal/llm.md for Notarius implementation behavior; and
  • contain no copied relative links that resolve only inside the PromptKit source repository.
• Update docs/roadmap/future.md to replace Scriptorium terminology in the native-session item with PromptKit. Keep the work deferred and state accurately that PromptKit v0.1.0 does not yet provide the desired direct request-level session field. Do not imply that existing prompt-variable propagation is native provider session support.
• Search all maintained Go, Markdown, YAML, JSON, and module files for remaining Scriptorium or scriptorium occurrences. Retain the old name only where necessary to explain the one-time version 3 migration or historical context.
• Validate affected relative documentation links.

Completion Criteria

• Current-behavior documentation outside docs/roadmap describes the implemented PromptKit integration only.
• Configuration and operational facts have one canonical owner.
• The integration document is Notarius-specific and does not duplicate or impersonate upstream package documentation.

Stage 6: Repository-Wide Verification

Complete the migration with focused and repository-wide validation.

Required Checks

Run:

git diff --check
go mod tidy
go test ./...
go vet ./...
go build ./cmd/notarius
go test -race ./internal/framework/llm ./internal/cli ./internal/modules/dnd/...

Also verify:

• go.mod and go.sum contain PromptKit and no Scriptorium dependency;
• the repository contains no obsolete Scriptorium Go identifiers or imports;
• any remaining textual use of Scriptorium is limited to intentional migration or historical explanation;
• maintained configuration examples parse successfully as version 4;
• tests remain deterministic, offline, and independent of real credentials;
• no prompt, schema, artifact, or checkpoint format changed unintentionally; and
• no secrets, prompt payloads, source content, or private infrastructure paths were introduced into code, errors, tests, or documentation.

Open Questions

None. The dependency version, compatibility policy, configuration migration, internal naming, provenance value, checkpoint treatment, session scope, documentation ownership, and verification boundaries are decided above.