# Architecture Policy

## Purpose

This document defines Promptkit's current high-level architecture and the
durable boundaries that implementation changes must preserve. The
[internal component overview](../internal/overview.md) inventories concrete
implemented packages without redefining these rules.

## System Shape

Promptkit is an importable Go library. It does not provide a runnable command,
an HTTP service, or another application process.

The module root contains package `promptkit`, which is the public facade. It
declares the module's public package boundary but does not yet provide a usable
exported framework API.

The implemented internal components consist of:

- `internal/domain`, which owns framework data values shared by later internal
  components;
- `internal/defaults`, which owns application-neutral framework defaults and
  constructs the default execution target; and
- `internal/filecatalog`, which discovers YAML files and provides source-path
  helpers for filesystem and `fs.FS` consumers;
- `internal/promptdef`, which loads and validates prompt definitions from
  filesystem and `fs.FS` sources;
- `internal/profile`, which loads, validates, and overlays execution profiles
  from filesystem and `fs.FS` sources;
- `internal/profile/builtin`, which embeds the built-in execution profile
  catalog; and
- `internal/prompt`, which renders prompt messages from Go templates.

The defaults and renderer depend on the domain model. Prompt-definition and
profile repositories use the domain model, file catalog, and YAML decoder. The
built-in profile repository supplies an embedded `fs.FS` to the profile
package. Artifact reading, output validation, model clients, orchestration, and
the public engine have not yet been extracted.

Future framework extraction must follow this dependency direction:

```text
downstream consumers, including Scriptorium
                    |
                    v
       root promptkit public facade
                    |
                    v
       internal framework components
                    |
                    v
        narrow injected abstractions
```

The facade may coordinate internal components once the public engine is
extracted. Internal components must depend on narrow abstractions for behavior
supplied from outside the library; they must not depend on consumers or on
Scriptorium. This diagram is the target dependency direction for later
extraction and does not assert that the public facade already assembles the
implemented foundation.

## Repository And Consumer Boundary

Scriptorium is a downstream application that will consume Promptkit through
the supported public facade. It is not a Promptkit package and must not become
an internal dependency.

Promptkit owns reusable, application-neutral library behavior. It does not own:

- binaries or executable packaging;
- CLI commands, parsing, streams, or exit codes;
- HTTP routes, servers, request DTOs, status mapping, or deployment policy;
- application configuration discovery or precedence;
- process lifecycle, operational state, or application logging; or
- consumer-specific filesystem or security policy.

Those concerns remain with Scriptorium or another consuming application.

## Package Ownership

The module root is the supported public facade. Framework implementation
packages belong under Go's `internal/` boundary unless a demonstrated, stable
consumer contract requires a public package.

Each package must have one cohesive responsibility and a clear dependency
direction. Internal packages must not expose their types merely to simplify
wiring, and the public facade must not leak internal representations through
exported signatures. New public packages require a durable consumer need that
cannot be served cleanly by the root facade.

The [internal component overview](../internal/overview.md) must be updated as
packages are implemented or their responsibilities change.

## Exported API Discipline

Export the smallest contract required by real consumers. Exported declarations
must have accurate GoDoc, stable semantics, and tests proportionate to their
compatibility risk. Avoid speculative extension points, aliases for internal
types, and public constructors that expose assembly details.

Once an exported API exists, its Go declaration and GoDoc own its exact public
contract. Architecture documentation owns boundary rules, not a duplicate API
reference.

## Error Boundaries

Internal failures must cross the public facade as errors meaningful to a Go
consumer without exposing private package types or transport-specific policy.
Wrapping should add useful context while preserving any public error identity
needed with `errors.Is` or `errors.As`.

Promptkit must not assign CLI exit codes or HTTP status codes. Consumers map
public library outcomes into their own transport behavior.

## Dependency Injection

External effects and consumer-selected policy must enter through narrow
interfaces or functions at the boundary that uses them. Dependencies should be
explicitly supplied during construction or invocation rather than read from
consumer configuration or hidden process-global state.

Interfaces should be owned by the code that consumes the behavior and should
contain only the operations that code requires. Provide defaults only for
application-neutral behavior; consumer-specific restrictions and adapters
remain injected from the consuming project.

## Repository Independence

Promptkit must build, test, and validate independently of Scriptorium. Do not
commit `go.work`, `go.work.sum`, or a local filesystem `replace` directive.
Temporary workspace or replacement configuration may support coordinated local
development, but it is not part of either repository's architecture or release
state.

## Current-State Maintenance

This policy distinguishes present implementation from constraints on future
framework extraction. Do not list planned packages as implemented components.
When extraction introduces a package, update the internal inventory and the
owning contract or subsystem document in the same change.