# Documentation Compliance Roadmap

## Status

The initial documentation refresh and its follow-up compliance work were
completed on 2026-07-26. The documentation prerequisite for Step 2 of the
[Promptkit migration roadmap](migration.md) is satisfied.

## Objective

Maintain an accurate, concise documentation baseline under the canonical
ownership policy, and close the remaining review findings before architectural
migration begins.

## Completed Refresh

The initial refresh:

- established the documentation and ADR policies and recorded
  [ADR 0001](../adr/0001-adopt-canonical-documentation-ownership.md);
- made `docs/development.md` the contributor entry point and added a canonical
  internal component overview;
- refocused architecture on normative boundaries and moved implementation
  detail into focused internal documents;
- consolidated CLI, configuration, HTTP, public Go, and integration contracts
  under distinct canonical owners;
- rewrote operations as a runbook, incorporated useful recovery guidance, and
  removed the standalone troubleshooting document;
- normalized maintained examples and added an offline HTTP request-example
  check;
- corrected the factual discrepancies found by the original audit, including
  the entry-path count, built-in profile catalog, prompt output optionality,
  input-map behavior, validation diagnostics, session-ID units, and CLI flag
  descriptions; and
- validated local links, configuration examples, smoke examples, tests, vet,
  and the documented build.

## Follow-Up Findings

The post-completion review found:

1. The effective precedence between `Config.Timeout` and a supplied
   `HTTPClient.Timeout` is not consistently expressed by the implementation,
   tests, and documentation.
2. The public Go contract overgeneralizes basename selection for single-file
   sources; prompt and profile files remain selected by YAML ID, while
   `WithSchemaFile` uses the schema file's base name.
3. The maintained HTTP request-example test pins incidental fixture values
   beyond the structural contract it needs to protect.
4. The Promptkit migration roadmap's overall status says no work is implemented
   even though its documentation-refresh step is complete.
5. One architecture invariant incorrectly describes configuration, prompt, and
   profile inputs as JSON rather than YAML.

## Follow-Up Implementation Sequence

### Stage 1: Resolve The Timeout Contract

1. Decide and document the precedence among:
   - `Config.Timeout`;
   - a non-zero timeout on a supplied `http.Client`; and
   - an explicit per-request `timeout_seconds` override.
2. Align `internal/llm` with that decision, removing any constructor state that
   is immediately discarded during generation.
3. Add or revise a behavior-level test that performs `Generate` with a supplied
   HTTP client and proves the selected timeout without relying only on private
   constructor state.
4. Update the canonical public Go contract, outbound OpenAI-compatible
   integration contract, and internal LLM document together.

**Gate:** There is one documented timeout-precedence rule, the implementation
follows it, and a request-level test protects it.

### Stage 2: Correct The Remaining Contract And Architecture Text

1. Clarify in the public Go contract that:
   - prompt and profile single-file sources are selected by their YAML IDs;
   - `WithPromptFile` resolves relative `content_file` paths from the prompt
     file's directory; and
   - `WithSchemaFile` exposes the schema through its base name.
2. Correct or remove the duplicate architecture invariant so it accurately
   distinguishes strict YAML configuration, prompt, and profile inputs from
   strict JSON HTTP input.
3. Recheck the affected statements against the public facade and source
   implementations without duplicating file-format definitions outside the
   configuration contract.

**Gate:** Public source-option behavior and strict-decoding invariants agree
with the implementation and retain one canonical owner.

### Stage 3: Refine The Maintained HTTP Example Check

1. Preserve an offline check that `examples/http-run.json` is accepted by the
   HTTP request contract.
2. Remove assertions that freeze prompt IDs, profile IDs, fixture paths, or
   example variable values unless a specific value protects an independently
   identified contract.
3. Rely on focused handler tests, rather than the maintained-example check, for
   exhaustive DTO-to-domain mapping behavior.
4. Run the affected HTTP adapter tests and confirm that the revised test still
   fails for structurally invalid example content.

**Gate:** The maintained example has durable structural protection without
duplicating mapping coverage or making legitimate fixture edits unnecessarily
expensive.

### Stage 4: Reconcile Status And Revalidate The Baseline

1. Update the Promptkit migration roadmap's overall status to distinguish the
   completed documentation step from the unimplemented migration steps.
2. Recheck local Markdown links and paths.
3. Verify both maintained configuration files through the real configuration
   loader.
4. Run the maintained render script and Go package example.
5. Run `go test ./...`, `go vet ./...`, and `go build ./cmd/scriptorium`.
6. Record completion of these follow-up stages here and confirm the
   documentation gate in the Promptkit migration roadmap.

**Gate:** Code, tests, examples, canonical contracts, architecture, and both
roadmap status documents agree. Promptkit migration Step 2 may then begin.

## Completion Criteria

This follow-up is complete when:

- timeout precedence is unambiguous, implemented, and protected by an
  execution-level test;
- public single-file source behavior is accurately documented;
- strict YAML and JSON boundaries are accurately stated;
- the HTTP example check protects structure without pinning incidental content;
- roadmap status accurately distinguishes completed and pending migration work;
  and
- links, examples, tests, vet, and build validation pass.

## Completion Record

Completed on 2026-07-26. The timeout contract, single-file source contract,
strict-decoding boundary, and maintained HTTP example check were reconciled.
Final validation confirmed local links and paths, both maintained configuration
files through the real loader, the maintained render and Go package examples,
`go test ./...`, `go vet ./...`, and `go build ./cmd/scriptorium`.