Add development policy and internal architecture docs

docs/internal/adapters.md

@@ -0,0 +1,139 @@
+# Adapter And Repository Internals
+
+## Purpose
+
+This document describes implemented adapter/repository boundaries and their current behavior.
+
+## Adapter Map
+
+- `internal/adapter/cli`: CLI command parsing, app wiring, stdout/stderr handling, exit codes.
+- `internal/adapter/http`: HTTP request/response mapping for `POST /v1/runs`.
+- `internal/promptdef`: filesystem prompt-definition repository.
+- `internal/profile`: filesystem execution-profile repository.
+- `internal/artifact`: input artifact reader.
+- `internal/prompt`: Go-template renderer.
+- `internal/llm`: OpenAI-compatible LLM client implementation.
+- `internal/validate`: output validator.
+- `internal/format`: prepared-run formatters for `render` output.
+
+## Inputs And Outputs
+
+CLI adapter:
+
+- Input: process args, filesystem config/assets, environment.
+- Output: exit code, stdout artifact/prepared output, stderr summaries/errors.
+
+HTTP adapter:
+
+- Input: JSON request body (`runRequestDTO`).
+- Output: JSON success/error body with mapped status codes.
+
+Filesystem repositories:
+
+- Input: prompt/profile YAML files.
+- Output: normalized domain definitions/profiles or typed errors.
+
+Artifact reader:
+
+- Input: `domain.ArtifactRef`.
+- Output: loaded `domain.Artifact`.
+
+LLM adapter:
+
+- Input: `domain.GenerateRequest`.
+- Output: `domain.GenerateResponse`.
+
+Validator:
+
+- Input: artifact body + output contract.
+- Output: validation result or runtime validation error.
+
+## Boundaries
+
+- Adapters convert external representations to domain requests and back.
+- Use-case decisions remain in `internal/usecase`.
+- External dependency details stay scoped to adapter packages.
+
+## Config Fields Used
+
+Primary app settings consumed by adapters:
+
+- `prompt_dir`
+- `profile_dir`
+- `schema_dir`
+- `server.addr`
+- `defaults.render_format`
+
+Execution profile/request settings used through runner:
+
+- `endpoint`, `model`, `temperature`, `max_tokens`, `top_p`, `timeout_seconds`, `api_key_env`, `reasoning_effort`, `extra_params`
+
+## External Dependencies
+
+- YAML decoding: `gopkg.in/yaml.v3` (strict known-fields mode in config/prompt/profile loaders).
+- JSON Schema validation: `github.com/santhosh-tekuri/jsonschema/v6`.
+- HTTP client/server: Go standard library.
+
+## Failure Behavior
+
+Strict decoding and input checks:
+
+- config/prompt/profile loaders reject unknown YAML fields.
+- HTTP DTO decoder rejects unknown JSON fields.
+- raw API key payload fields are rejected by strict decoding in profile/http paths.
+
+Artifact refs:
+
+- Supported reference types: `inline`, `file`.
+- Unsupported types return `ErrUnsupportedRefType`.
+
+LLM adapter:
+
+- endpoint appends `/chat/completions`.
+- non-2xx responses map to request failure errors.
+- malformed responses (including missing/empty first choice content) are errors.
+
+Validator:
+
+- `basic`, `json`, `json_schema` content failures return `ValidationFailed` results.
+- schema load/compile/path failures are runtime errors.
+
+HTTP error mapping:
+
+- maps domain/use-case errors to stable HTTP code + error code/message.
+- avoids returning internal wrapped-cause details in response payload.
+
+## CLI Adapter Semantics
+
+Implemented commands:
+
+- `run`
+- `render`
+- `serve`
+
+Behavior highlights:
+
+- `run` exit `2` indicates validation failed after generation.
+- `render` does not call the LLM.
+- `serve` exposes HTTP handler only; no built-in auth.
+- `render` supports `--format text|json`; `render` does not expose `--schema-dir`.
+- deprecated aliases `--prompt-id` and `--profile-id` are still accepted.
+
+## Tests To Inspect Before Changing
+
+- `internal/adapter/cli/run_test.go`
+- `internal/adapter/http/handler_test.go`
+- `internal/promptdef/repository_test.go`
+- `internal/profile/repository_test.go`
+- `internal/artifact/reader_test.go`
+- `internal/prompt/renderer_test.go`
+- `internal/llm/openai_compatible_client_test.go`
+- `internal/validate/standard_validator_test.go`
+- `internal/format/prepared_run_test.go`
+
+## Architectural Invariants
+
+- Adapter packages do not own runner decision logic.
+- External request/response strictness is part of contract stability.
+- Prepared-render output never includes resolved API key values.
+- Outbound OpenAI-compatible request includes only currently serialized fields (`model`, `messages`, optional `temperature`, `max_tokens`, `top_p`, optional `response_format`).