promptkit/docs/roadmap/planning-assessment.md

Audit Remediation Planning Assessment

Purpose And Authority

Work through the unresolved design and evidence-dependent choices in the audit remediation roadmap before writing its staged implementation plan. Each numbered topic below is an assessment unit: gather the stated evidence, compare viable approaches, and record a recommendation before proceeding to the next topic.

The catalog's six accepted decisions remain authoritative. This assessment selects ways to implement those decisions; it does not reopen them or repeat the repository-wide audits. Catalog numbers below identify the relevant findings, not additional implementation stages. All assessment topics are initially pending.

Assessment Method And Outputs

Read the contributor guide and applicable policies before each topic. Reuse existing audit evidence, source inspection, and successful checks where sufficient. Prefer graph discovery for callers and dependencies, then inspect the relevant code, contracts, and tests. Follow the configuration-boundary ADR.

This is analysis, not remediation. Do not change production code, dependencies, installed toolchains, public contracts, or repository tests during the assessment. No prototype or alternative implementation is needed. Use existing offline benchmarks and tools where helpful; temporary measurement harnesses outside the repository are appropriate only when needed to answer a specific question. Record their setup sufficiently to interpret or repeat the results. Do not use live inference, credentials, or private production data.

Append an assessment record beneath each completed topic containing:

• Evidence: repository commit, concrete declarations/callers/tests, relevant dependency version, and measurements or commands actually used.
• Alternatives: plausible approaches and their semantic, maintenance, and resource tradeoffs. Do not manufacture alternatives to an obvious correction.
• Recommendation: the selected design or a justified proposed deferral, affected boundaries, and reasoning. Distinguish observed results from inference.
• Plan handoff: consequential signatures, fields, algorithms, or ownership transitions to specify; dependencies; migration/documentation impact; and implementation-time validation needed.
• Status: assessed, or a specific remaining uncertainty and the next bounded investigation needed. Assessment completion does not mean remediation complete.

For measurements, record the selected Go version, workload size/shape, and the relevant time, allocations, bytes, or retention evidence. Use small ordinary cases and larger valid cases to distinguish fixed overhead from scaling. Repeat noisy measurements only as needed; do not introduce benchmark thresholds, a generalized benchmark project, or a recurring release gate. Code-based work counts can establish avoidable traversal without timing every helper. Do not present estimated improvements as measured results from unimplemented code.

Recommendations should settle consequential implementation choices, not private helper names or equivalent coding details. Proceed between topics without new human-review or publication gates. If evidence requires changing an accepted decision or broadening scope, identify that question for the maintainer rather than silently selecting a new contract.

1. Establish The Evidence And Toolchain Baseline

Catalog: 1; applies to subsequent measurements.

Collect the current commit and worktree state, dependency versions, available Go installations, and the effective toolchain used by existing development and release commands. Compare the selected local toolchain against the specific networking fixes identified in the security audit, using authoritative upstream information where needed. Distinguish library/client applicability from server or platform-only findings and uncertainty about downstream builds.

Recommend the toolchain to use and any environment update needed before remediation validation. Record an unavailable patched toolchain as environment work to schedule, not permission to install one during assessment or to stop independent source analysis. Retain the accepted separation between maintainer selection and consumer minimum; do not add consumer advisories or scan gates.

2. Specify Direct ConfigKit Source Handoff

Catalog: 3, 5; informs 24.

Inspect the pinned ConfigKit Mapping contract and implementation at the snapshot/error boundary, plus both PromptKit convenience helpers and their callers. Establish which ordinary field projections remain, when values are captured, and how unsupported values, cycles, and shared graphs reach deferred diagnostics. Inventory existing fixtures using formerly converted types.

Recommend the exact removal boundary for the compatibility converter, supported handoff cases, and migration examples. Identify which current tests remain meaningful and which assert intentionally removed accommodation. Do not design a replacement converter, pre-validation pass, or upstream feature. Existing upstream ownership evidence is sufficient; exhaustive ConfigKit limit testing is not an assessment deliverable.

3. Specify Self-Contained Schema Resolution And Compilation

Catalog: 6, 15, 21; coordinates with 32.

Inspect the pinned schema compiler's resource registration/loading facilities, the four direct/prepared and host-file/fs.FS paths, native-schema projection, and runner validation interfaces. Establish where root loading, reference resolution, compilation, cancellation, and malformed-output short-circuiting occur.

Use a compact semantic case inventory to distinguish references resolved inside the supplied document from references needing another document. Include local fragments, anchors, recursion, and supported identifiers/base-URI behavior; preserve existing dialect support rather than adding it. Do not equate an external-looking reference string with external resource loading without checking resolution semantics.

Recommend the shared compilation boundary, needed source adapters and internal interface signatures, and external-resource rejection/error path. Identify obsolete loaders/tests and retained containment, single-file, freezing, and direct-validation cases. Specify how the provider receives the self-contained document unchanged in meaning. No bundler, schema rewriting prototype, or live provider compatibility experiment is needed.

4. Specify Ownership And Retention Remedies

Catalog: 4, 16, 18.

Trace public artifact adaptation and prepared-handle creation, claim, discard, details, and namespace-view operations. Inspect which references keep an engine alive and which synchronization owns state changes. Trace session normalization to its retained copies. Use reference/lifetime analysis first; use an existing allocation profile only if the retained graph is unclear.

Recommend the artifact contract/documentation changes under accepted ownership transfer, retaining the defensive copy initially. Specify the prepared-handle ownership identity and state transitions without relying on distinct zero-sized allocations comparing unequal. Identify the session-string detachment point. List relevant concurrent and mutation regressions for implementation, without building a new ownership framework or changing lifetimes during assessment.

5. Specify Error Ownership And Preparation-Stage Information

Catalog: 7, 8, 9; informs 25.

Trace representative collaborator failures through internal wrapping and public translation, including direct lookup failures and nested public sentinels. Inspect body-reader errors at initial decoding and end verification, current redaction, context precedence, and retry classification. Trace diagnostic preparation versus dispatch, including legitimate completed no-dispatch cases.

Recommend how owning-operation information and preparation-stage failures are represented and propagated. Specify the distinction between stream I/O failure, malformed/truncated content, size overflow, and cancellation using existing boundaries where possible. Give a small expected-outcome matrix of public category, retained cause, diagnostic completion, and dispatch behavior. Retained causes may match multiple sentinels; category exclusivity is not the target.

6. Specify Authentication Overflow Reporting And Adapter Ownership

Catalog: 2, 26, 27; uses topic 5's error/stage conclusions.

Inspect public/domain diagnostic DTOs, outcome labels, body ownership, HTTP evidence, authentication recognition, and facade projection. Determine whether the selected overflow outcome fits existing fields or needs an explicit additive representation. Inventory actual smoke-copy consumers rather than assuming full reports need cloning.

Recommend concrete field/type or outcome changes and their public/internal mapping. State the facts reported for overflow: acceptance unknown, explicit limit evidence, and independently available HTTP status/timing. Explain the interaction with non-success statuses and cancellation without discarding established independently known evidence. Preserve neutral reporting and privacy.

Specify the bounded read/overflow detection operation around the accepted 1 MiB allowance, including exact-boundary, missing/inaccurate length, and close behavior. Recommend the outbound protocol-adapter seam and narrow target-copy operation. Keep the body-bound fix independently implementable before adapter relocation; do not add a public budget option or general diagnostic plugin framework.

7. Assess JSON Copying Compatibility And Provider Overlay Cost

Catalog: 19, 24; uses topic 2's converter-removal boundary.

Inventory callers of facade copying, runtime JSON validation/copying, prepared snapshots, and configuration overlay. Build a compact compatibility matrix for accepted concrete types, nil/indirection handling, exact numbers, empty keys, error behavior, bounds, and mutable ownership. Separate trusted-value copying from fallible input acceptance and source encoding.

Collect existing overlay benchmark/allocation evidence, supplemented only where needed with representative depth, breadth, overlapping/disjoint maps, and array replacement cases within current limits. Identify repeated visits/copies and their construction-time cost; respect the existing bounded-depth qualification.

Recommend which traversal can actually be removed, the shared operation's contract, and the overlay algorithm/ownership model. Prefer retaining a small distinct walker over a configurable framework when policies differ. Recommend implementing or explicitly deferring the optional overlay optimization based on expected benefit and complexity; identify estimates as such. Do not add errors, panics, or silent fallbacks to an infallible facade projection.

8. Assess Requirement Evidence Accumulation And Traversal

Catalog: 10, 23.

Trace ownership and merging of condition-evidence sets and the shared versus node-specific responsibilities of if/with. Inspect real-renderer comparison tests and scope/reachability cases. Collect operation counts or targeted baseline measurements across increasing left-heavy recognized conditions; include a small ordinary case so pathological scaling is not the only input.

Recommend an accumulation/merge algorithm and a narrow branch-orchestration boundary, explaining expected work without promising a new universal complexity contract. Keep the algorithmic fix distinct from traversal cleanup. Specify preserved dot/root scopes, inactive computed names, and conservative incomplete analysis. No interpreter, expanded grammar, or expression limit is proposed.

9. Assess Bounded Repair-Feedback Encoding

Catalog: 17.

Inspect feedback framing, JSON escaping, truncation, and the locations retaining full diagnostics and prior output. Measure current formatting with ordinary, large, and heavily escaped synthetic diagnostic strings, separating final output size from temporary allocations. Identify which complete serializations account for the avoidable memory cost.

Compare a bounded incremental approach with the current implementation using source-level algorithm and complexity reasoning; no alternative encoder needs to be built. Recommend an encoding/truncation approach and its preservation cases, or a justified proposed deferral if benefit does not warrant complexity. Any deferral must acknowledge the outstanding allocation issue. Do not cap raw diagnostics, discard stored errors, or assert an exact peak-heap guarantee.

10. Assess Namespace Listing Index Tradeoffs

Catalog: 20.

Inspect inventory capture, namespace identity, ordering, filtered retrieval, cancellation, and result detachment. Gather baseline time/allocation evidence for unfiltered listings and sparse, dense, and absent namespace matches at ordinary and larger valid inventory sizes. Consider both a single request and repeated namespace inspection, without assuming every consumer repeatedly lists entries.

Compare captured buckets/ranges with the existing scan. Account for construction work, retained index memory, and query output copying; do not optimize query time while ignoring its construction/retention tradeoff. Recommend a specific layout and query algorithm, or a justified proposed deferral. No pagination, runtime cache, or new ordering/cancellation guarantee is needed.

11. Select Remaining Refactoring, Test, And Cleanup Boundaries

Catalog: 11–14, 22, 25, 28–34; consolidate related conclusions above.

Reuse existing audit evidence and perform targeted caller checks rather than reauditing these findings. Identify the configuration helper boundaries, generation attempt-result fields, and accounting seam consistent with topics 2–8. Locate the real coordinator assembly to use in scheduling tests and the behavioral coverage that must survive wrapper retirement.

Select one independent bundled-catalog test oracle and the smaller distinct risks owned elsewhere. Identify privacy-formatting cases, public schema-file coverage from topic 3, and replacement assertions for opaque hashes. Map obsolete fields/helpers to actual callers and tests, including serialized definition-hash effects. Record the owning documentation for each correction/migration.

Recommend a concrete removal/extraction inventory, preservation tests, and ordering dependencies. Do not infer that self-tests justify production helpers, or that lack of example coverage makes supported APIs obsolete. This is not a new deletion sweep, exact helper-design exercise, or complexity-metric target.

12. Consolidate Recommendations For Implementation Planning

Review the assessment records in order and reconcile cross-topic choices. Produce a compact handoff covering all 34 catalog entries: selected remedy or explicit proposed deferral, supporting assessment topic, consequential design choice, dependencies, and implementation-time validation. Findings whose remedy was already settled need only a brief mapping, not another investigation.

Ensure source conversion disappears rather than migrating into shared copying; schema simplification and compilation agree; errors/stages precede accounting refactoring; the authentication fix can precede relocation; and actual coordinator tests precede wrapper removal. Separate optional cleanup from fixes so a deferral does not obstruct unrelated remediation.

Record any scope/contract question that still needs maintainer direction with a recommendation and viable alternative. A deferral is a recommendation, not silent authorization to drop accepted work. Unavailable measurements or tooling must be identified, together with whether they could change the recommendation; do not present a conditional choice as a settled implementation instruction.

Once consequential choices are settled, the subsequent implementation plan can define focused ordered stages, selected designs, migration/documentation work, and proportionate validation. Implementation correctness, race regressions, post-change measurements, and release checks remain work for implementation and release preparation. No claim of remediation completion follows from this assessment, and no new recurring release or human-review gate is introduced.