diff --git a/docs/roadmap/documentation.md b/docs/roadmap/documentation.md deleted file mode 100644 index 4862ff8..0000000 --- a/docs/roadmap/documentation.md +++ /dev/null @@ -1,150 +0,0 @@ -# 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 positive 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 single-file source contract, strict-decoding -boundary, and maintained HTTP example check were reconciled. A subsequent -assembled-engine review corrected the timeout work into two independent -layers: a construction-time transport cap and a per-generation context -deadline, with explicit request zero disabling only the latter. Deterministic -public `Engine.Run` coverage now protects the interaction with caller -deadlines, profile and request values, the framework default, `Config.Timeout`, -and supplied HTTP-client caps. - -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 a temporary-output build. The Promptkit -Step 1 documentation gate remains complete after this layered-timeout -correction.