diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 4c174ae..b597665 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -29,9 +29,9 @@ checks passed during the audits; they do not cover all identified defects. - Asset operations classify a missing service-provided release identity as a malformed observation. Existing page-only reads retain their current minimal response requirements. -- Preparation path anchoring is explicit in the public documentation. The - recommended interpretation retains the supplied-directory anchor; the - alternative is discussed under Open Decisions. +- Preparation resolves the containing checkout root automatically, matching + other orchestration operations. Standalone preparation retains the supplied + directory as its base. - Delivery documentation accurately describes identity requirements for empty prebuilt results and credential preflight before full artifact verification. @@ -101,17 +101,18 @@ flag source. This is narrower than replacing all `GOFLAGS` or disabling the persistent Go environment. Preserve the other effective flags and the current proxy, private-module, authentication, checksum, cache, workspace, and local-toolchain -behavior. Preserve Go's existing checksum-update behavior and directory -selection; this unit adds no requirement for an immediate `go.mod` in a supplied -package directory. +behavior. Directory selection follows the checkout-root resolution in unit 6; +within the resolved selection, preserve Go's existing checksum-update behavior +and ordinary module discovery. Standalone package-directory preparation retains +upward declaration discovery. **Completion evidence:** exercise both inherited and persistent `-modfile` settings against different module graphs. Preparation consumes the ordinary -selected graph, including when Go discovers its declaration above the working -directory. Verify the existing network/private-module/cache settings remain -available and that unrelated flags retain their behavior. Use test-owned -`GOMODCACHE` directories for every synthetic-module download. Keep the existing -binary CI preparation ordering and cancellation/error propagation covered. +selected graph, including standalone use where Go discovers its declaration +above the working directory. Verify the existing network/private-module/cache +settings remain available and that unrelated flags retain their behavior. Use +test-owned `GOMODCACHE` directories for every synthetic-module download. Keep the +existing binary CI preparation ordering and cancellation/error propagation covered. Document the preparation flag override in its GoDoc and the [Go environment guide](../internal/gotool.md). Update command fixtures for the @@ -179,27 +180,35 @@ to work, and existing page/write-progress outcomes remain accurate. Retain `TestBackendFindReleaseDoesNotRequireWriteResponseFields` or equivalent behavioral coverage. Update the integration guide's error description as needed. -### 6. Clarify dependency preparation's path anchor +### 6. Resolve preparation's checkout root automatically -**Status:** open; targeted interpretation follows Open Decision 1. -**Source:** interfaces finding 3. +**Status:** open. **Source:** interfaces finding 3. -**Owners:** `DependencyPreparationRequest` GoDoc and consumer preparation guidance; -selection code only if the alternative is chosen. +**Owners:** the preparation facade, shared Git/selection boundaries, +`DependencyPreparationRequest` GoDoc, and consumer preparation guidance. -Under the recommendation, document `RepositoryDir` as the supplied base -directory for preparation, `ModuleDir` as relative to that base, and empty -`ModuleDir` as selecting that base. Explain that callers sharing a location with -other orchestration APIs should supply the resolved checkout root when they -intend repository-root-relative selection. Keep standalone directory preparation -and the CLI's existing root normalization. +Resolve the containing checkout root from `RepositoryDir` before applying +`ModuleDir`. Within a checkout, interpret `ModuleDir` relative to that root; +empty selection means the root module, consistently with `Check`, `Build`, and +`Deliver`. For standalone use outside a Git checkout, retain the supplied +directory as the base and apply the existing relative module selection there. -**Completion evidence:** compare the wording and examples with current root, -nested, symlink-resolved, and standalone-directory behavior. Reuse existing -selection tests for a documentation-only correction. If anchoring behavior -changes instead, add behavioral coverage for calls from within a checkout and -for standalone preparation, including failed discovery behavior, and document -the changed interpretation. +Keep this normalization inside ReleaseKit so callers can reuse a repository +location across operations without normalization code or a new setting. This +applies [ADR 0002's priority](../adr/0002-routine-releases.md) of minimizing +caller-owned release work. Retain the CLI's existing root normalization and +shared symlink/containment rules. Distinguish standalone use from discovery +failures; cancellation, permission failures, and other Git errors remain +errors rather than silently selecting another base. + +**Completion evidence:** cover calls from the checkout root and its +subdirectories, default and explicit nested-module selections, symlink-resolved +paths, standalone directories, and discovery failures. Include combined coverage +with unit 2 showing that preparation and subsequent orchestration select the +same module from the same repository location and `ModuleDir`, even with an +ambient alternate module file. Preserve standalone package-directory discovery +and the existing CLI behavior. Update GoDoc and consumer guidance to describe +the selected interpretation and the change for checkout-subdirectory callers. ### 7. Clarify empty prebuilt results @@ -258,28 +267,3 @@ Mark this roadmap complete when all eight work units and their corresponding audit findings have been addressed and verified, including the selected path-anchor interpretation. The initial pass that creates this roadmap changes only this document. - -## Open Decisions - -### 1. Dependency preparation's repository anchor - -**Recommendation:** retain the supplied `RepositoryDir` as the preparation base -and clarify its meaning in GoDoc and consumer guidance. This corrects the -ambiguity without changing existing selection behavior, preserves standalone -preparation, and keeps the current CLI experience. The tradeoff is that API -callers reusing a directory within a checkout must supply its resolved root -when composing root-relative preparation with `Check`, `Build`, or `Deliver`. -This is a recommended resolution, not a claim that the audit established a -requirement to retain that difference. - -**Viable alternative:** resolve the containing checkout root when the supplied -directory belongs to a Git checkout, and preserve supplied-directory preparation -for standalone use. This aligns ordinary checkout-based calls with the other -facades and reduces caller normalization. It changes the interpretation of -existing calls from checkout subdirectories and adds discovery behavior. The -implementation would need to distinguish standalone use from discovery failures -without silently treating every Git error as permission to use another anchor. -Adopting it would require focused selection tests and updated consumer guidance. - -A Git-checkout prerequisite is unnecessary for either correction; the current -standalone use remains part of the baseline considered by both choices.