151 lines
6.8 KiB
Markdown
151 lines
6.8 KiB
Markdown
# 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.
|