diff --git a/docs/roadmap/audit/01-correctness.md b/docs/roadmap/audit/01-correctness.md index 1117300..3795005 100644 --- a/docs/roadmap/audit/01-correctness.md +++ b/docs/roadmap/audit/01-correctness.md @@ -30,9 +30,9 @@ availability or acceptance of arbitrary JSON Schema features. **Priority:** P2. Confirmed data-conversion defect. -**Code:** [providerValueForMapping](../../../provider_values.go:51), used by -[ProfileSource](../../../profiles.go:33) and -[BackendSource](../../../backends.go:100). +**Code:** [providerValueForMapping](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/provider_values.go#L51), used by +[ProfileSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/profiles.go#L33) and +[BackendSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/backends.go#L100). **Circumstances:** A caller supplies a valid `json.Number` in provider `ExtraParams` that cannot be represented exactly by the helper's chosen native @@ -79,10 +79,10 @@ and contrast with the already-preserving runtime path. **Priority:** P2. Confirmed schema-packaging gap; remediation requires choosing how provider-facing schemas accommodate the existing local-reference feature. -**Code:** [preparedValidation.SchemaDocument](../../../internal/validate/standard_validator.go:63), -[StandardValidator.PrepareValidation](../../../internal/validate/standard_validator.go:74), -[FSValidator.PrepareValidation](../../../internal/validate/standard_validator.go:126), -and [structuredOutputFromValidationPlan](../../../internal/usecase/runner.go:419). +**Code:** [preparedValidation.SchemaDocument](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/internal/validate/standard_validator.go#L63), +[StandardValidator.PrepareValidation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/internal/validate/standard_validator.go#L74), +[FSValidator.PrepareValidation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/internal/validate/standard_validator.go#L126), +and [structuredOutputFromValidationPlan](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/internal/usecase/runner.go#L419). **Circumstances:** A JSON Schema output contract uses a root schema referring to another file within the configured schema source. The diff --git a/docs/roadmap/audit/02-efficiency.md b/docs/roadmap/audit/02-efficiency.md index 0e2be80..72d8479 100644 --- a/docs/roadmap/audit/02-efficiency.md +++ b/docs/roadmap/audit/02-efficiency.md @@ -42,8 +42,8 @@ guarantee, cache, caller limit, or release gate is proposed. **Priority:** P2. Requirement-inspection path; most relevant to deeply nested conditions rather than ordinary small templates. -**Code:** [evaluateCommand](../../../internal/prompt/requirements.go:142) and -[mergeConditionEvaluations](../../../internal/prompt/requirements.go:318). +**Code:** [evaluateCommand](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/prompt/requirements.go#L142) and +[mergeConditionEvaluations](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/prompt/requirements.go#L318). Each comparison recursively evaluates its operands, then allocates fresh `missingVariables` and `contentInputs` maps and copies both operands' accumulated @@ -73,7 +73,7 @@ and partial-result behavior; interpreting more expressions is not necessary. **Priority:** P3. Construction-time improvement with an existing depth bound. -**Code:** [overlayProviderMap](../../../internal/configuration/targets.go:131). +**Code:** [overlayProviderMap](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/configuration/targets.go#L131). The helper deep-copies the entire lower map before considering overrides. When both values at a key are maps, it recursively invokes itself on a descendant @@ -106,9 +106,9 @@ validation/bounds; do not replace ConfigKit's configuration machinery. **Priority:** P3. Scalability opportunity for engines with many namespaces. -**Code:** [filterIdentityList](../../../internal/engine/engine.go:306), -[ListPrompts](../../../internal/engine/engine.go:270), and the -[configuration inventory methods](../../../internal/configuration/listing.go:14). +**Code:** [filterIdentityList](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/engine/engine.go#L306), +[ListPrompts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/engine/engine.go#L270), and the +[configuration inventory methods](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/configuration/listing.go#L14). A named-namespace request first obtains a detached copy of all N identities and then scans it to build its k matching results. Even an absent namespace costs diff --git a/docs/roadmap/audit/03-complexity.md b/docs/roadmap/audit/03-complexity.md index 855d268..a0ed855 100644 --- a/docs/roadmap/audit/03-complexity.md +++ b/docs/roadmap/audit/03-complexity.md @@ -39,10 +39,10 @@ dependencies were changed, and no empirical testing or benchmarks were needed. ## 1. Consolidate Schema Compilation And Express The Runner's Actual Interface -**Code:** [validator interfaces](../../../internal/validate/validator.go:10), -[schema implementations](../../../internal/validate/standard_validator.go:45), -[runner preparation](../../../internal/usecase/runner.go:398), and -[engine assembly](../../../internal/engine/engine.go:133). +**Code:** [validator interfaces](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/validate/validator.go#L10), +[schema implementations](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/validate/standard_validator.go#L45), +[runner preparation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/usecase/runner.go#L398), and +[engine assembly](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/engine/engine.go#L133). **Complexity:** The validator maintains direct validation and prepared validation, with separate filesystem and `fs.FS` compilation paths. Compiler @@ -72,10 +72,10 @@ without treating this refactor alone as its fix. ## 2. Decompose Configuration Validation And Resource Materialization -**Code:** [validateEffective](../../../internal/configuration/load.go:410), -[materializePrompt](../../../internal/configuration/prompts.go:58), -[buildExecutionProfiles](../../../internal/configuration/targets.go:14), and -[resolution callbacks](../../../internal/configuration/resolve_prompts.go:10). +**Code:** [validateEffective](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/configuration/load.go#L410), +[materializePrompt](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/configuration/prompts.go#L58), +[buildExecutionProfiles](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/configuration/targets.go#L14), and +[resolution callbacks](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/configuration/resolve_prompts.go#L10). **Complexity:** `validateEffective` combines namespace checks, reference indexes, backend settings, capacity arithmetic, smoke metadata, profile bounds, and prompt @@ -105,10 +105,10 @@ Avoid a reflection-driven field schema that obscures the domain rules. ## 3. Untangle Requirement Traversal, Expression Evaluation, And Evidence -**Code:** [requirement walker](../../../internal/prompt/requirements.go:356), -[syntax dispatch](../../../internal/prompt/requirements.go:451), -[condition evaluation](../../../internal/prompt/requirements.go:93), and -[command traversal](../../../internal/prompt/requirements.go:652). +**Code:** [requirement walker](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/prompt/requirements.go#L356), +[syntax dispatch](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/prompt/requirements.go#L451), +[condition evaluation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/prompt/requirements.go#L93), and +[command traversal](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/prompt/requirements.go#L652). **Complexity:** The approximately thousand-line file contains mutually recursive syntax walking and partial expression evaluation, branch reachability, caller @@ -137,9 +137,9 @@ but separate; a mechanical file split would not fix it. ## 4. Clarify Ownership And Policies Across The JSON Value Walkers -**Code:** [source mapping conversion](../../../provider_values.go:31), -[bounded JSON copying](../../../internal/jsonvalue/jsonvalue.go:67), and -[public-value copying](../../../convert.go:406). +**Code:** [source mapping conversion](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/provider_values.go#L31), +[bounded JSON copying](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/jsonvalue/jsonvalue.go#L67), and +[public-value copying](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/convert.go#L406). **Complexity:** Three recursive reflection-based paths independently handle interfaces/pointers, maps, sequences, scalars, and nil values. Each adds its own @@ -168,10 +168,10 @@ complexity; retain separate small adapters where their policies differ. ## 5. Extract Attempt Accounting From Generation Control Flow -**Code:** [Coordinator.generate](../../../internal/generation/coordinator.go:98), -[generateInjected](../../../internal/generation/coordinator.go:203), -[execute](../../../internal/generation/coordinator.go:303), and -[diagnostic evidence consumers](../../../internal/usecase/smoke_tester.go:246). +**Code:** [Coordinator.generate](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/generation/coordinator.go#L98), +[generateInjected](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/generation/coordinator.go#L203), +[execute](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/generation/coordinator.go#L303), and +[diagnostic evidence consumers](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/usecase/smoke_tester.go#L246). **Complexity:** The coordinator interleaves permit acquisition, dispatch, cancellation, retry decisions, observer events, diagnostic evidence, and diff --git a/docs/roadmap/audit/05-resources.md b/docs/roadmap/audit/05-resources.md index 0abe625..ae27cd3 100644 --- a/docs/roadmap/audit/05-resources.md +++ b/docs/roadmap/audit/05-resources.md @@ -30,9 +30,9 @@ existing protected behavior; they do not cover all findings below. **Priority:** P2. Unbounded remote-response consumption; a finite limit would be a new policy decision, not enforcement of an existing documented byte limit. -**Code:** [runOpenRouterKey](../../../internal/usecase/smoke_authentication.go:66), -[recognizedOpenRouterKeyResponse](../../../internal/usecase/smoke_authentication.go:139), -and [diagnostic HTTP execution](../../../internal/llm/http_evidence.go:129). +**Code:** [runOpenRouterKey](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/smoke_authentication.go#L66), +[recognizedOpenRouterKeyResponse](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/smoke_authentication.go#L139), +and [diagnostic HTTP execution](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/llm/http_evidence.go#L129). **Circumstances:** An authentication endpoint returns HTTP 200 with a large or continuously growing body. Recognition calls unrestricted `io.ReadAll` and then @@ -63,10 +63,10 @@ artifacts, or generated output. **Priority:** P2. Potentially exponential allocation before upstream resource checks can run. -**Code:** [providerMapForMapping](../../../provider_values.go:19), -[providerValueForMapping](../../../provider_values.go:31), -[ProfileSource](../../../profiles.go:33), and -[BackendSource](../../../backends.go:100). +**Code:** [providerMapForMapping](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/provider_values.go#L19), +[providerValueForMapping](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/provider_values.go#L31), +[ProfileSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/profiles.go#L33), and +[BackendSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/backends.go#L100). **Circumstances:** A caller builds a small acyclic Go value graph containing repeated map/slice references. Each level can point twice to the same child: @@ -107,10 +107,10 @@ configuration limits to fix this pre-handoff allocation problem. **Priority:** P3. Avoidable retained-memory dependency after use/discard. -**Code:** [PreparedExecution.owner](../../../internal/usecase/prepared_execution.go:24), -[Discard](../../../internal/usecase/prepared_execution.go:96), -[claim](../../../internal/usecase/prepared_execution.go:172), and -[payload clearing](../../../internal/usecase/prepared_execution.go:188). +**Code:** [PreparedExecution.owner](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/prepared_execution.go#L24), +[Discard](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/prepared_execution.go#L96), +[claim](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/prepared_execution.go#L172), and +[payload clearing](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/prepared_execution.go#L188). **Circumstances:** A consumer retains a completed or discarded handle for its supported `Details` access, while replacing or dropping the originating engine. @@ -141,7 +141,7 @@ collaborators is implied. **Priority:** P3. Avoidable memory amplification on validation failures. -**Code:** [formatRepairDiagnostics](../../../internal/usecase/repairer.go:119). +**Code:** [formatRepairDiagnostics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/repairer.go#L119). **Circumstances:** A failed schema validation produces a large diagnostic or many diagnostics and repair is enabled. The formatter normalizes every string, marshals @@ -170,9 +170,9 @@ implementation opportunity, not a claim that the existing contract promises a **Priority:** P3. Avoidable backing-buffer retention in retained metadata. -**Code:** [NormalizeSessionID](../../../internal/domain/session.go:10), -[preparation](../../../internal/usecase/runner.go:312), and -[prepared metadata construction](../../../internal/usecase/runner.go:491). +**Code:** [NormalizeSessionID](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/domain/session.go#L10), +[preparation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/runner.go#L312), and +[prepared metadata construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/runner.go#L491). **Circumstances:** A direct or rendered session ID contains substantial leading or trailing whitespace around a short valid identifier. `strings.TrimSpace` diff --git a/docs/roadmap/audit/06-error-handling.md b/docs/roadmap/audit/06-error-handling.md index 7b6481f..1038a55 100644 --- a/docs/roadmap/audit/06-error-handling.md +++ b/docs/roadmap/audit/06-error-handling.md @@ -44,9 +44,9 @@ not repeated here. **Priority:** P2. Confirmed public error-classification defect. -**Code:** [publicErrorFor](../../../errors.go:63), -[mapPublicError](../../../errors.go:16), and -[wrapGenerationError](../../../internal/usecase/runner.go:271). +**Code:** [publicErrorFor](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/errors.go#L63), +[mapPublicError](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/errors.go#L16), and +[wrapGenerationError](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/internal/usecase/runner.go#L271). **Failure condition:** An injected `LLMClient` or `ArtifactReader` returns an error obtained from another PromptKit operation. Ordinary mapped errors retain @@ -56,7 +56,7 @@ regardless of which operation the outer runner classified. **Expected:** A model-client failure matches `ErrLLMGenerate`; an artifact-reader failure matches `ErrArtifactLoad`. The injected cause remains available through -`errors.Is`, as their [public GoDoc](../../../engine.go:49) specifies. Preserving +`errors.Is`, as their [public GoDoc](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/engine.go#L49) specifies. Preserving the nested cause may also preserve its public categories; it must not replace the category for the operation that just failed. @@ -89,7 +89,7 @@ and context identities. **Priority:** P2. Confirmed loss of failure provenance and cause. -**Code:** [decodeOpenAIChatResponse](../../../internal/llm/openai_compatible_client.go:373). +**Code:** [decodeOpenAIChatResponse](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/internal/llm/openai_compatible_client.go#L373). **Failure condition:** A 2xx response body returns a non-EOF I/O error other than `context.Canceled` or `context.DeadlineExceeded`, either during the first decode @@ -99,7 +99,7 @@ while reading the response stream after headers were received. **Expected:** Distinguish an underlying read/transport failure from evidence of invalid JSON or trailing data. Retain the read cause through a redacting error so callers can inspect it with `errors.Is`/`errors.As`, consistent with the -[transport category](../../../engine.go:65). Do not report trailing data when the +[transport category](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/engine.go#L65). Do not report trailing data when the reader failed without supplying any. This does not change the established classification of invalid/truncated JSON or introduce transport retries. @@ -133,9 +133,9 @@ private transport details. **Priority:** P2. Confirmed mismatch with the diagnostic error contract. -**Code:** [runInference](../../../internal/usecase/smoke_tester.go:207), -[generation preparation](../../../internal/generation/coordinator.go:96), and -[request payload validation](../../../internal/llm/openai_compatible_client.go:511). +**Code:** [runInference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/internal/usecase/smoke_tester.go#L207), +[generation preparation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/internal/generation/coordinator.go#L96), and +[request payload validation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/internal/llm/openai_compatible_client.go#L511). **Failure condition:** An inference diagnostic's effective settings are invalid in a way detected by built-in request construction rather than target selection. @@ -144,7 +144,7 @@ is one public example. The coordinator returns `llm.ErrInvalidRequest` before dispatch with no attempt evidence. `runInference` treats every generation error as a concluded diagnostic failure. -**Expected:** The [SmokeTest contract](../../../smoke_diagnostics.go:238) says invalid +**Expected:** The [SmokeTest contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/smoke_diagnostics.go#L238) says invalid kinds, settings, and selections return an ordinary Go error before diagnostic work. A locally invalid request should follow that path and expose the public invalid-request category. This is distinct from a provider rejecting a validly diff --git a/docs/roadmap/audit/07-security.md b/docs/roadmap/audit/07-security.md index b666aa0..38fd7d1 100644 --- a/docs/roadmap/audit/07-security.md +++ b/docs/roadmap/audit/07-security.md @@ -62,10 +62,10 @@ operations described below rather than inferred from interface-call traces. **Priority:** P2. Build/deployment security finding, not a newly discovered PromptKit algorithm defect. -**Relevant code:** [declared Go minimum](../../../go.mod:3), -[default HTTP-client construction](../../../internal/llm/openai_compatible_client.go:58), -[generation dispatch](../../../internal/llm/openai_compatible_client.go:211), and -[diagnostic dispatch](../../../internal/llm/http_evidence.go:129). +**Relevant code:** [declared Go minimum](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/go.mod#L3), +[default HTTP-client construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/llm/openai_compatible_client.go#L58), +[generation dispatch](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/llm/openai_compatible_client.go#L211), and +[diagnostic dispatch](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/llm/http_evidence.go#L129). **Condition and impact:** The local toolchain used for this audit is Go 1.27.0. Applications built with that patch can exercise affected standard-library @@ -111,9 +111,9 @@ HTTP/2 ban, or a new recurring release gate. response boundary. This is the same mechanism as resource-management audit finding 1, not a second independent remediation item. -**Relevant code:** [authentication recognition](../../../internal/usecase/smoke_authentication.go:139), -[authentication probe execution](../../../internal/usecase/smoke_authentication.go:66), -and [diagnostic HTTP execution](../../../internal/llm/http_evidence.go:129). +**Relevant code:** [authentication recognition](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/usecase/smoke_authentication.go#L139), +[authentication probe execution](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/usecase/smoke_authentication.go#L66), +and [diagnostic HTTP execution](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/llm/http_evidence.go#L129). **Condition:** A consumer explicitly invokes an `openrouter_key` authentication diagnostic. The selected endpoint, a compromised provider, or an intermediary diff --git a/docs/roadmap/audit/08-testing.md b/docs/roadmap/audit/08-testing.md index cc1b819..1247f1d 100644 --- a/docs/roadmap/audit/08-testing.md +++ b/docs/roadmap/audit/08-testing.md @@ -62,8 +62,8 @@ rather than becoming duplicate remediation projects. **Priority:** P2. Missing protection for a documented confidentiality boundary. -**Relevant code:** [RunRequest formatting](../../../formatting.go:5) and the -analogous existing [SmokeTestRequest privacy test](../../../smoke_test_contract_test.go:135). +**Relevant code:** [RunRequest formatting](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/formatting.go#L5) and the +analogous existing [SmokeTestRequest privacy test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/smoke_test_contract_test.go#L135). **Deficiency:** `RunRequest.String`, `GoString`, and their shared formatter all have 0% combined statement coverage. The suite protects formatting of generated @@ -86,12 +86,12 @@ Reflection-based disclosure is explicitly outside this formatter guarantee. **Priority:** P2. An exported source-selection path is entirely unprotected. -**Relevant code:** [WithSchemaFile](../../../engine.go:212), -[SetSchemaFile](../../../internal/engine/engine.go:75), and -[fileSource](../../../internal/engine/engine.go:211). +**Relevant code:** [WithSchemaFile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/engine.go#L212), +[SetSchemaFile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/engine/engine.go#L75), and +[fileSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/engine/engine.go#L211). **Deficiency:** All three functions have 0% combined coverage. The existing -[single-file validator test](../../../internal/validate/standard_validator_test.go:596) +[single-file validator test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/validate/standard_validator_test.go#L596) constructs `FSValidator` directly with `fstest.MapFS`; it does not test the public option, host-file selection, or its engine wiring. @@ -113,9 +113,9 @@ helper-by-helper test matrix or model-provider access. **Priority:** P2. Conversion and ownership coverage misses known data-integrity and deferred-error risks. -**Relevant tests:** [programmatic source ownership/order](../../../sources_contract_test.go:14) -and [programmatic construction](../../../construction_contract_test.go:226). -**Implementation:** [providerValueForMapping](../../../provider_values.go:31). +**Relevant tests:** [programmatic source ownership/order](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/sources_contract_test.go#L14) +and [programmatic construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/construction_contract_test.go#L226). +**Implementation:** [providerValueForMapping](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/provider_values.go#L31). **Deficiency:** The converter has only 11.9% combined coverage. The principal source-ownership test mutates a flat string-valued map. It does not establish @@ -143,10 +143,10 @@ coverage for the separately identified shared-graph issue belongs with that fix. **Priority:** P2. Covered code paths lack important boundary-case assertions. -**Relevant tests:** [public generation failures](../../../generation_error_contract_test.go:111), -[direct mapper cases](../../../errors_internal_test.go:13), -[body cancellation](../../../internal/llm/prepared_generation_test.go:161), and -[inference diagnostic cases](../../../internal/usecase/smoke_inference_test.go:14). +**Relevant tests:** [public generation failures](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/generation_error_contract_test.go#L111), +[direct mapper cases](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/errors_internal_test.go#L13), +[body cancellation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/llm/prepared_generation_test.go#L161), and +[inference diagnostic cases](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/usecase/smoke_inference_test.go#L14). **Deficiency and demonstrated blind spots:** @@ -180,9 +180,9 @@ precedence, best-effort non-2xx detail parsing, and status-only retry policy. **Priority:** P2. Missing assembled validation-to-wire assertion. -**Relevant tests:** [prepared execution source freezing](../../../prepared_execution_contract_test.go:19), -its [referenced schema fixture](../../../prepared_execution_contract_test.go:809), -and [local reference validation](../../../internal/validate/standard_validator_test.go:627). +**Relevant tests:** [prepared execution source freezing](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/prepared_execution_contract_test.go#L19), +its [referenced schema fixture](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/prepared_execution_contract_test.go#L809), +and [local reference validation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/validate/standard_validator_test.go#L627). **Deficiency:** Local tests establish that referenced schemas compile and validate. The prepared-execution test checks that the injected client's schema @@ -210,11 +210,11 @@ promise support for arbitrary provider schema dialect features. **Priority:** P3. Remove or rewrite change-detector assertions, retaining the substantive file-reading tests. -**Relevant assertions:** [size-hint test](../../../internal/artifact/reader_test.go:287) -and [benchmark correctness check](../../../internal/artifact/reader_benchmark_test.go:156). +**Relevant assertions:** [size-hint test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/artifact/reader_test.go#L287) +and [benchmark correctness check](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/artifact/reader_benchmark_test.go#L156). **Deficiency:** Both independently calculate a hex SHA-256 digest and require -that exact value. The [public Artifact.Hash contract](../../../types.go:290) +that exact value. The [public Artifact.Hash contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/types.go#L290) expressly leaves its format and algorithm unspecified. A legitimate algorithm or encoding change would fail tests unrelated to the requested behavior. @@ -222,7 +222,7 @@ or encoding change would fail tests unrelated to the requested behavior. opaque equality relationships needed for each test. For the under/overreported size cases, comparing with the inline reader for the same complete body still detects hashing only a reported-size prefix. The existing -[source-parity test](../../../internal/artifact/reader_test.go:27) already owns +[source-parity test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/artifact/reader_test.go#L27) already owns repeatability, same-content equality, and changed-content inequality. Retain body, actual-size, metadata, and read-boundary assertions. The benchmark may reuse an opaque expected hash prepared outside measurement or rely on the @@ -232,10 +232,10 @@ owning behavioral test; it need not maintain its own SHA-256 contract. **Priority:** P3. Consolidation/removal candidate for duplicated assertions. -**Relevant tests:** [internal complete catalog table](../../../internal/configuration/bundled_test.go:12), -[public option/inventory table](../../../bundled_openrouter_contract_test.go:54), -[HTTP payload matrix](../../../bundled_execution_contract_test.go:51), and -[bundled smoke defaults](../../../bundled_smoke_contract_test.go:16). +**Relevant tests:** [internal complete catalog table](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/configuration/bundled_test.go#L12), +[public option/inventory table](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/bundled_openrouter_contract_test.go#L54), +[HTTP payload matrix](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/bundled_execution_contract_test.go#L51), and +[bundled smoke defaults](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/bundled_smoke_contract_test.go#L16). **Deficiency:** The current count of 17, complete ID inventory, selected ID-to-model mappings, tier-plugin data, and diagnostic default model recur diff --git a/docs/roadmap/audit/09-interfaces.md b/docs/roadmap/audit/09-interfaces.md index 054ef93..3c67e02 100644 --- a/docs/roadmap/audit/09-interfaces.md +++ b/docs/roadmap/audit/09-interfaces.md @@ -33,9 +33,9 @@ to change those behaviors. **Priority:** P2. A documented ownership permission permits data races and inconsistent input snapshots. -**Relevant interfaces/code:** [ArtifactReader GoDoc](../../../types.go:294), -[public reader adapter](../../../artifact_reader.go:19), and -[copyBytes](../../../convert.go:490). +**Relevant interfaces/code:** [ArtifactReader GoDoc](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/types.go#L294), +[public reader adapter](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/artifact_reader.go#L19), and +[copyBytes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/convert.go#L490). **Contract defect:** The interface says that `Read` may be called concurrently and that the reader may reuse or mutate the returned artifact and body after @@ -72,11 +72,11 @@ the selected lifetime, without globally serializing unrelated engine work. **Priority:** P2. The public inspection contract describes valid results as impossible and incorrectly limits the sources that can satisfy a requirement. -**Relevant interfaces/code:** [Engine.InspectProfile](../../../engine.go:313), -[ProfileInspection.APIKeyRequired](../../../types.go:372), +**Relevant interfaces/code:** [Engine.InspectProfile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/engine.go#L313), +[ProfileInspection.APIKeyRequired](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/types.go#L372), [profile-inspection consumer example](../../consumers/pkg-promptkit.md#inspect-a-profile-before-prompt-work), -[effective-target construction](../../../internal/configuration/targets.go:99), -and [credential availability check](../../../internal/usecase/runner.go:611). +[effective-target construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/configuration/targets.go#L99), +and [credential availability check](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/usecase/runner.go#L611). **Contract defect:** Both method and field GoDoc claim that `APIKeyRequired` is mutually exclusive with a nonblank `EffectiveModelParams.APIKeyEnv`. They @@ -97,7 +97,7 @@ reject this valid combination or report credential readiness incorrectly. **Evidence:** A temporary public-API diagnostic demonstrated that combination and successful preparation. The existing -[effective-target test](../../../internal/configuration/targets_test.go:88) +[effective-target test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/configuration/targets_test.go#L88) also includes a required profile with an explicit environment source. **Potential remediation:** Describe the flag as a local credential-availability @@ -114,8 +114,8 @@ provider parameters. **Relevant interfaces/code:** [integration request-body contract](../../integrations/openai-compatible-chat.md#request-body), [profile defaulting reference](../../formats.md#defaults-and-overrides), -[overlayProviderMap](../../../internal/configuration/targets.go:133), and -[runtime override merge](../../../internal/usecase/runner.go:562). +[overlayProviderMap](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/configuration/targets.go#L133), and +[runtime override merge](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/usecase/runner.go#L562). **Contract defect:** The integration document says backend, profile, and request extra-parameter maps all use whole-map replacement. Actual configured profile @@ -135,7 +135,7 @@ only `request_only: true` does remove the configured entries. **Evidence:** A temporary public-API diagnostic observed both forms through an injected client and confirmed the configured merged fields through a controlled built-in HTTP transport. No external request was made. The existing -[effective-target test](../../../internal/configuration/targets_test.go:70) +[effective-target test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/configuration/targets_test.go#L70) also exercises recursive configured overlay. **Potential remediation:** Replace the stale configuration-precedence claim @@ -148,9 +148,9 @@ do not add another merge policy or duplicate its full configuration reference. **Priority:** P3. Small but concrete public-contract inconsistencies. -**Relevant interfaces/code:** [ProfileInspection.ProfileID](../../../types.go:364), -[ListPrompts GoDoc](../../../listing.go:90), and -[literal profile identity test](../../../profile_inspection_contract_test.go:13). +**Relevant interfaces/code:** [ProfileInspection.ProfileID](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/types.go#L364), +[ListPrompts GoDoc](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/listing.go#L90), and +[literal profile identity test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/profile_inspection_contract_test.go#L13). **Contract defect:** `ProfileInspection.ProfileID` is described as trimmed, but configured IDs and lookups preserve meaningful whitespace exactly. diff --git a/docs/roadmap/audit/10-equivalence.md b/docs/roadmap/audit/10-equivalence.md index 83790bd..75ec7e0 100644 --- a/docs/roadmap/audit/10-equivalence.md +++ b/docs/roadmap/audit/10-equivalence.md @@ -32,19 +32,19 @@ equivalence promise, is the preservation target. ### Evidence -- [TestJSONSchemaNumericConstraintsRetainJSONPrecision](../../../internal/validate/standard_validator_test.go:721) +- [TestJSONSchemaNumericConstraintsRetainJSONPrecision](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator_test.go#L721) runs the same exact-number constraints through operating-system and `fs.FS` validators using `jsonSchemaValidatorSources`. Both must distinguish adjacent large integers, preserve precise decimal boundaries, and accept the same valid instances. -- [TestJSONSchemaDecodingRequiresOneCompleteDocument](../../../internal/validate/standard_validator_test.go:805) +- [TestJSONSchemaDecodingRequiresOneCompleteDocument](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator_test.go#L805) uses that same source matrix to require equivalent schema/instance framing and the distinction between operational schema errors and rejected output. -- [TestSchemaReferencesPreserveEscapedFilenames](../../../internal/validate/standard_validator_test.go:492) +- [TestSchemaReferencesPreserveEscapedFilenames](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator_test.go#L492) applies the same reference cases to both source implementations, with an explicit platform exception for filenames illegal on Windows. -- [TestStandardValidatorPreparedSchemaSurvivesSourceRemoval](../../../internal/validate/standard_validator_test.go:228) - and [TestFSValidatorPreparedSchemaSurvivesSourceMutation](../../../internal/validate/standard_validator_test.go:416) +- [TestStandardValidatorPreparedSchemaSurvivesSourceRemoval](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator_test.go#L228) + and [TestFSValidatorPreparedSchemaSurvivesSourceMutation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator_test.go#L416) separately require the same captured schema to accept an integer-valued object and reject a string-valued one after its source changes. Their source operations differ, but the prepared validation responsibility matches. @@ -54,7 +54,7 @@ not require identical filesystem representations or diagnostic strings. ### Implementation -[StandardValidator and FSValidator](../../../internal/validate/standard_validator.go:74) +[StandardValidator and FSValidator](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator.go#L74) each implement `PrepareValidation` and direct `validateJSONSchema`. The four paths repeat compiler setup, root-resource handling, cancellation boundaries, compilation/error wrapping, and construction or use of executable schema @@ -97,17 +97,17 @@ correctness finding, not solved by this extraction. ### Evidence -- [TestPublicLLMClientAdapterGivesClientOwnedNestedValues](../../../llm_adapter_internal_test.go:14) +- [TestPublicLLMClientAdapterGivesClientOwnedNestedValues](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/llm_adapter_internal_test.go#L14) requires nested provider maps, schema values, messages, and cache metadata to remain independent when an injected client mutates and retains its request. -- [TestRunnerPreparedExecutionDetachesTransferredSnapshotSources](../../../internal/usecase/prepared_execution_test.go:634) +- [TestRunnerPreparedExecutionDetachesTransferredSnapshotSources](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/usecase/prepared_execution_test.go#L634) separately requires nested provider maps and schema values to survive source mutation, repeated `Details` calls, and execution without aliasing. -- [TestCopyHandlesIndirectionAndIsolatesNestedMutations](../../../internal/jsonvalue/jsonvalue_test.go:156) +- [TestCopyHandlesIndirectionAndIsolatesNestedMutations](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/jsonvalue/jsonvalue_test.go#L156) exercises the underlying JSON-value ownership responsibility with typed collections and repeated acyclic children. The adjacent scalar/collection tests protect compatible concrete types and exact `json.Number` values. -- [TestCopyAndCopyMapApplyDistinctEmptyKeyRules](../../../internal/jsonvalue/jsonvalue_test.go:204) +- [TestCopyAndCopyMapApplyDistinctEmptyKeyRules](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/jsonvalue/jsonvalue_test.go#L204) explicitly demonstrates a necessary policy distinction: general schema objects can have empty keys, while provider maps cannot. @@ -117,16 +117,16 @@ normalization, and copying on arbitrary Go values. ### Implementation -The facade's [copyAny/copyReflectValue](../../../convert.go:406) implements a +The facade's [copyAny/copyReflectValue](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/convert.go#L406) implements a separate recursive reflection copier for values projected into client requests, prepared details, results, and profile inspections. Internal prepared-state -cloning uses [clonePreparedRun](../../../internal/usecase/prepared_execution.go:226) -and [jsonvalue.Copy/CopyMap](../../../internal/jsonvalue/jsonvalue.go:30). +cloning uses [clonePreparedRun](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/usecase/prepared_execution.go#L226) +and [jsonvalue.Copy/CopyMap](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/jsonvalue/jsonvalue.go#L30). The latter package already owns compatible JSON-tree copying and validation. Ordinary runtime provider values reach facade projection after JSON-value validation/copying. The runner also copies its schema document through -[structuredOutputFromValidationPlan](../../../internal/usecase/runner.go:419) +[structuredOutputFromValidationPlan](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/usecase/runner.go#L419) before projecting it. Thus these normal runtime paths have a common accepted value domain, even though their entry-point policies are different. @@ -172,19 +172,19 @@ replacing them with one “all copy functions are equivalent” test. ### Evidence -- [TestAnalyzeRequirementsClassifiesKnownConditions](../../../internal/prompt/requirements_test.go:268) +- [TestAnalyzeRequirementsClassifiesKnownConditions](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/prompt/requirements_test.go#L268) verifies required/optional classification for selected and skipped `if` branches, and directly compares the recognized branch choice with the real Go renderer. This anchors recognized condition semantics in actual rendering. -- [TestAnalyzeRequirementsHandlesWithDotAndNestedReachability](../../../internal/prompt/requirements_test.go:332) +- [TestAnalyzeRequirementsHandlesWithDotAndNestedReachability](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/prompt/requirements_test.go#L332) requires the same selected/skipped classification for `with` and nested `if`, while separately protecting `with`'s changed dot and preserved root caller-map access. -- [TestAnalyzeRequirementsReportsUnresolvedDecisionAndContentConditions](../../../internal/prompt/requirements_test.go:369) +- [TestAnalyzeRequirementsReportsUnresolvedDecisionAndContentConditions](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/prompt/requirements_test.go#L369) protects conditional dependencies and meaningful incompleteness for unknown decisions. It also establishes that an unresolved condition around plain text alone does not make discovery incomplete. -- [TestAnalyzeRequirementsDoesNotHideCallerMapScopes](../../../internal/prompt/requirements_test.go:14) +- [TestAnalyzeRequirementsDoesNotHideCallerMapScopes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/prompt/requirements_test.go#L14) compares several scope forms against actual template execution while allowing incomplete analysis for constructs outside recognition scope. @@ -195,7 +195,7 @@ or completely interpret arbitrary templates. ### Implementation The `IfNode` and `WithNode` cases in -[requirementWalker.visit](../../../internal/prompt/requirements.go:451) +[requirementWalker.visit](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/prompt/requirements.go#L451) independently perform inactive-path traversal, condition evaluation, then/else reachability selection, dependency-counter comparison, and limitation recording. `with` adds a different body-dot calculation. `branchReach`, condition diff --git a/docs/roadmap/audit/11-boundaries.md b/docs/roadmap/audit/11-boundaries.md index e4541d2..2ead0c9 100644 --- a/docs/roadmap/audit/11-boundaries.md +++ b/docs/roadmap/audit/11-boundaries.md @@ -33,10 +33,10 @@ release blockers. ## 1. Retire The Test-Only Capacity Client As A Production Scheduling Surface -**Relevant code:** [capacity.NewClient and client.Generate](../../../internal/capacity/client.go:17), -[generation constructors and dispatch](../../../internal/generation/coordinator.go:37), -[engine assembly](../../../internal/engine/engine.go:157), and -[runner scheduling test](../../../internal/usecase/runner_test.go:2391). +**Relevant code:** [capacity.NewClient and client.Generate](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/capacity/client.go#L17), +[generation constructors and dispatch](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/generation/coordinator.go#L37), +[engine assembly](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/engine/engine.go#L157), and +[runner scheduling test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/runner_test.go#L2391). **Basis:** The engine selects `generation.NewBuiltIn` or `NewInjected` for every production engine. The coordinator owns active-permit acquisition around each @@ -77,10 +77,10 @@ identified; current test reachability alone does not establish one. ## 2. Put OpenRouter Authentication Protocol Details Behind The Outbound Adapter -**Relevant code:** [authenticationProbe.runOpenRouterKey](../../../internal/usecase/smoke_authentication.go:66), -[recognizedOpenRouterKeyResponse](../../../internal/usecase/smoke_authentication.go:139), -[diagnostic endpoint derivation](../../../internal/usecase/smoke_selection.go:166), -and [HTTP authentication transport](../../../internal/llm/http_evidence.go:111). +**Relevant code:** [authenticationProbe.runOpenRouterKey](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/smoke_authentication.go#L66), +[recognizedOpenRouterKeyResponse](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/smoke_authentication.go#L139), +[diagnostic endpoint derivation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/smoke_selection.go#L166), +and [HTTP authentication transport](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/llm/http_evidence.go#L111). **Basis:** `internal/usecase` currently interprets OpenRouter-specific HTTP statuses and the account-response keys `data`, `label`, `is_free_tier`, and @@ -97,7 +97,7 @@ knowledge. The [architecture policy](../../policy/architecture.md#architectural- calls for encapsulating external integration details in internal adapters. The parser is already functionally isolated, making the ownership seam fairly small. The authentication tests in -[smoke_authentication_test.go](../../../internal/usecase/smoke_authentication_test.go:64) +[smoke_authentication_test.go](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/smoke_authentication_test.go#L64) also show that this is provider protocol behavior rather than application selection policy. @@ -134,10 +134,10 @@ read is a separate resource/security finding; relocation alone does not fix it. ## 3. Narrow Smoke-Value Copy Helpers To Their Actual Ownership Boundaries -**Relevant code:** [domain.CloneSmokeTestRequest](../../../internal/domain/smoke_diagnostics.go:157), -[domain.CloneSmokeTestReport](../../../internal/domain/smoke_diagnostics.go:179), -[smokeReportTarget](../../../internal/usecase/smoke_tester.go:432), and -[public smoke-value conversion](../../../smoke_diagnostics.go:279). +**Relevant code:** [domain.CloneSmokeTestRequest](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/domain/smoke_diagnostics.go#L157), +[domain.CloneSmokeTestReport](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/domain/smoke_diagnostics.go#L179), +[smokeReportTarget](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/smoke_tester.go#L432), and +[public smoke-value conversion](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/smoke_diagnostics.go#L279). **Basis:** `CloneSmokeTestRequest` is called only by its own domain test; actual request ownership is established by public-to-domain conversion. @@ -172,7 +172,7 @@ ownership behavior. Preserve provider-map error propagation, caller-owned result values, and credential/endpoint redaction. Keep the meaningful -[public conversion ownership test](../../../smoke_conversion_internal_test.go:13) +[public conversion ownership test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/smoke_conversion_internal_test.go#L13) and relevant use-case report tests. If genuine internal whole-report snapshots are needed, retaining an explicitly used domain cloner is a reasonable alternative. This finding does not require sharing public/internal DTO types diff --git a/docs/roadmap/audit/12-deadcode.md b/docs/roadmap/audit/12-deadcode.md index e6eb9d9..b8f1a57 100644 --- a/docs/roadmap/audit/12-deadcode.md +++ b/docs/roadmap/audit/12-deadcode.md @@ -27,15 +27,15 @@ for deleting a supported public feature or imposing a new release gate. ## 1. Remove Backend Presence Bookkeeping With No Runtime Consumer -**Relevant code:** [loaded.backends](../../../internal/configuration/load.go:122), -[backendFields and presence capture](../../../internal/configuration/load.go:215), -[effective backend construction](../../../internal/configuration/targets.go:14), -and [Backend.QueueCapacitySet](../../../internal/domain/domain.go:187). +**Relevant code:** [loaded.backends](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/load.go#L122), +[backendFields and presence capture](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/load.go#L215), +[effective backend construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/targets.go#L14), +and [Backend.QueueCapacitySet](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/domain.go#L187). **Evidence:** Construction allocates a per-backend field-state map and fills it through `captureFields(..., state.backends)`. No production code reads the recorded backend states. The only lookup of the captured queue state is in -[TestLoadDefaultsAbsentQueueCapacity](../../../internal/configuration/load_test.go:755). +[TestLoadDefaultsAbsentQueueCapacity](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/load_test.go#L755). Unlike profile presence, backend presence is not consumed while constructing effective execution targets. @@ -46,7 +46,7 @@ explicit queue setting from a derived default. The registry's capacity-policy projection uses `ConcurrencyLimit` and `QueueCapacity`, not this flag. **Why obsolete:** Queue defaulting and its provenance are already handled by -[resolveBackends](../../../internal/configuration/resolve_targets.go:11) and +[resolveBackends](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/resolve_targets.go#L11) and ConfigKit's derived-default record. Typed final values drive runtime capacity; the retained side map and Boolean do not contribute to that behavior or to the public inspection view. No documented compatibility or planned-feature need for @@ -66,11 +66,11 @@ under the [configuration-boundary ADR](../../adr/0001-configuration-boundary.md) ## 2. Retire Legacy Fields In The Captured Prompt Representation -**Relevant code:** [PromptDefinition.OutputFormat](../../../internal/domain/domain.go:148), -[PromptMessageTemplate.ContentFile](../../../internal/domain/domain.go:173), -[prompt materialization](../../../internal/configuration/prompts.go:58), -[resolveOutputContract](../../../internal/usecase/runner.go:639), and -[definition hashing](../../../internal/promptdef/hash.go:12). +**Relevant code:** [PromptDefinition.OutputFormat](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/domain.go#L148), +[PromptMessageTemplate.ContentFile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/domain.go#L173), +[prompt materialization](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/prompts.go#L58), +[resolveOutputContract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/runner.go#L639), and +[definition hashing](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/promptdef/hash.go#L12). **Evidence:** Supported engine construction requires and validates a complete output contract. Materialization sets `definition.Validation` to that contract @@ -113,10 +113,10 @@ representation, not part of the public stable DTO shapes. ## 3. Remove Unused Diagnostic State And A Discarded Helper Result -**Relevant code:** [reachabilityProbeOutcome.initialEndpoint](../../../internal/usecase/smoke_reachability.go:24), -[HTTP report assembly](../../../internal/usecase/smoke_tester.go:376), -[fileSource](../../../internal/engine/engine.go:211), and -[SetSchemaFile](../../../internal/engine/engine.go:75). +**Relevant code:** [reachabilityProbeOutcome.initialEndpoint](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/smoke_reachability.go#L24), +[HTTP report assembly](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/smoke_tester.go#L376), +[fileSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/engine/engine.go#L211), and +[SetSchemaFile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/engine/engine.go#L75). **Evidence:** The reachability probe assigns its private outcome's `initialEndpoint`, but the smoke tester never reads that member. It records @@ -144,15 +144,15 @@ though an extra private field/result is unnecessary. **Relevant code and evidence:** -- [filecatalog.RelativePath](../../../internal/filecatalog/catalog.go:71) is +- [filecatalog.RelativePath](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/filecatalog/catalog.go#L71) is called only by `TestRelativePathNested`. Current source discovery and source-relative resource resolution use other helpers; no production or public-facade caller uses this wrapper around `filepath.Rel`. -- [resourceNamespaceFromID](../../../internal/domain/resource_identity.go:34) +- [resourceNamespaceFromID](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/resource_identity.go#L34) is called only by `TestResourceNamespaceFromID`. Actual namespace inventory and filtering paths do not call it. The exported identity-validation and qualification operations remain active and are not candidates for removal. -- [runner_test.go:stringPtr](../../../internal/usecase/runner_test.go:2592) +- [runner_test.go:stringPtr](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/runner_test.go#L2592) has no callers, including in tests. Both reachability analysis and Staticcheck `U1000` report it. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 4c080f5..50819c3 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -469,6 +469,16 @@ names/claims to separate historical audit evidence from stale current guidance. ## Stage 17: Validate And Close The Sprint +**Completed:** Findings 1–7 are implemented and finding 8's runtime behavior is +preserved. With Go 1.27.3, `go test -race ./...` and `go vet ./...` passed, +including maintained examples. All tracked Go files are formatted; full diff +whitespace and repository hygiene checks passed. A local Markdown destination +and heading scan checked 580 links in 63 files; 153 historical code references +were corrected to their audit commits and verified against those Git objects. +Remaining validating copies are confined to acceptance/overlay boundaries; +trusted copies and transfers retain the documented ownership boundaries. No +release, push, or publication was performed. + **Scope:** combined final state, all findings and deferred checks. 1. Resolve remaining deferred compilation/tests; format changed Go files. Run diff --git a/docs/roadmap/responsibility-simplification.md b/docs/roadmap/responsibility-simplification.md index 71c69b3..abc2b41 100644 --- a/docs/roadmap/responsibility-simplification.md +++ b/docs/roadmap/responsibility-simplification.md @@ -9,8 +9,7 @@ library's substantive feature set and selected ownership boundaries. This roadmap captures the target state and work arising from the accepted [responsibility audit](audit/A1-responsibility.md). Findings 1–7 are selected for remediation; finding 8 selects preservation of runtime input behavior. -The selected implementation is delivered; final combined validation and -repository hygiene checks remain pending. +The selected implementation and combined final validation are complete. The work began from the `f660b6e` decision baseline and production audit baseline `1ff6d77`. The audit owns historical evidence and decision rationale; @@ -48,8 +47,8 @@ throughput, complexity, or numerical-precision guarantees. ## Selected Work The following sections record the accepted work and its rationale. The target -above is implemented; final combined checks are tracked in the implementation -plan rather than inferred from the audit's baseline tests. +above is implemented; final checks are recorded in the implementation plan +rather than inferred from the audit's baseline tests. ### Resolved Targets And Direct Wire Construction @@ -222,7 +221,8 @@ match the result. Caller review should confirm that retired private workflows and duplicate state are actually gone rather than renamed or relocated. The audit's test results describe the original baseline, not evidence of the -replacement implementation. Record actual implementation outcomes separately. +replacement implementation. The implementation plan records the focused and +combined checks performed on the delivered changes. No significant product decisions remain open. Release selection/publication and retirement of the older completed audit documents are separate work from this roadmap.