Remove completed documentation roadmap
This commit is contained in:
@@ -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.
|
|
||||||
Reference in New Issue
Block a user