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