Plan credential preflight for forge delivery

docs/roadmap/forge-boundary.md

@@ -1,4 +1,4 @@
-# Roadmap: separate shared delivery from forge adapters
+# Roadmap: forge delivery boundary and credential preflight
 
 Status: accepted; implementation has not started.
 
@@ -10,6 +10,8 @@ choices, task sequencing, and verification.
 Introduce an internal boundary between shared hosted-release delivery and the
 Gitea implementation. The result should support adding another forge through
 an adapter while reusing ReleaseKit's release and asset-delivery policy.
+Add operation-specific credential preflight through that boundary so delivery
+stops on credential problems before expensive preparation or builds.
 
 ReleaseKit's `Publish` operation validates and publishes source through Git.
 Its `Deliver` operation verifies tagged source and delivers release notes and
@@ -42,6 +44,10 @@ and the subsequent token-file and forbidden-file changes.
 - CLI credential resolution supplies an explicit token from the configured
   environment variable or token file. The profile describes a Gitea repository;
   it has no forge selector.
+- CLI loading checks token availability, but forge API authentication first occurs
+  through delivery requests after application dependency preparation and managed
+  builds. Library delivery also checks a blank token only at the later Gitea
+  request boundary. There is no dedicated authenticated credential preflight.
 
 The [Gitea integration guide](../integrations/gitea.md) and public Go declarations
 document the baseline contracts. Current behavioral tests provide regression
@@ -68,6 +74,7 @@ and protocol requirements are implemented.
 
 Shared internal code owns:
 
+- Automatic credential preflight coordination before expensive delivery work.
 - Captured source identity, local tag/commit checks, committed release notes,
   managed or prebuilt artifact coordination, and local artifact verification.
 - The existing logical rules for accepting matching hosted content, reporting
@@ -81,16 +88,46 @@ generic delivery workflow has no dependency on `internal/gitea`. The facade or
 private composition code constructs the concrete backend and supplies it to
 shared delivery.
 
+### Credential preflight
+
+Delivery automatically checks the credentials required for its selected backend.
+Local checks establish availability and valid destination settings; a read-only
+backend probe establishes authentication and access to the configured repository.
+Reliable evidence of insufficient required permissions stops the operation.
+Unexposed permissions remain unverified; successful reads establish no blanket
+guarantee that later writes will succeed. Preflight performs no test writes and
+preserves ordinary delivery authorization and recovery handling.
+
+Library and ordinary CLI delivery perform preflight before managed builds and
+full artifact verification. CI loads the verified tagged profile first, then
+performs preflight before application dependency preparation. A callable facade
+operation lets consumers check a destination before their own preparation,
+without requiring a release tag or note to exist.
+
+Failures distinguish missing or rejected credentials, insufficient permissions,
+an inaccessible destination, and unavailable or unverifiable service responses.
+Delivery reports `not_attempted` for these pre-write failures. Diagnostics retain
+useful causes while excluding tokens. Each check describes access at that time;
+later operations retain their normal checks.
+
+Required credentials follow operation scope. Candidate checking and standalone
+builds remain credential-free. Source publication continues using Git's native
+SSH/HTTPS authentication and existing remote guards, independently of hosted
+delivery credentials. This feature adds no Gitea-token requirement to `Publish`.
+
 ### Backend responsibilities
 
 The Gitea adapter owns destination validation specific to Gitea, API routes,
 authentication headers, request and response formats, pagination, multipart
 uploads, attachment downloads, and HTTP-specific error interpretation.
+It also owns authenticated credential probes and interpretation of available
+permission evidence, using repository-scoped checks without requiring unrelated
+account or administration scopes.
 
-The internal contract supplies the logical operations needed to inspect a
-hosted tag, find or create a release, enumerate assets, read asset content, and
-upload an asset. Release and asset references carry backend-owned handles;
-shared orchestration works with logical identity and content rather than
+The internal contract supplies the logical operations needed to preflight
+credentials, inspect a hosted tag, find or create a release, enumerate assets,
+read asset content, and upload an asset. Release and asset references carry
+backend-owned handles; shared orchestration works with logical identity and content rather than
 interpreting Gitea's positive integer IDs.
 
 The contract also carries the evidence needed for existing recovery behavior:
@@ -116,13 +153,16 @@ and follow-up lookup behavior.
 
 Local verification reuse, streaming, cancellation, stream closure, temporary
 build ownership, and upload cleanup remain part of the affected workflow.
+Read-only credential preflight precedes expensive local artifact work; local
+content verification still completes before hosted release or asset writes.
 Credential environment/file selection and forbidden-file validation retain
 their existing responsibilities. Backend-specific address validation stays
 with that backend.
 
-The public destination replacement and required forge selection are deliberate
-API and configuration changes for the next minor release. Migration guidance
-describes the consumer edits under the project's direct-cutover approach.
+The public destination replacement, required forge selection, and earlier
+credential failures are deliberate changes for the next minor release.
+Migration guidance describes consumer edits under the project's direct-cutover
+approach.
 Current contract documents and examples change with implementation; historical
 release notes retain their original contents.
 
@@ -130,6 +170,8 @@ Completion means shared delivery and asset policy have independent internal
 ownership, Gitea implements the backend boundary, existing Gitea contracts work
 through it, and the neutral public destination and explicit selection are
 consistent across the API, configuration, examples, and documentation.
+Credential preflight operates through the backend boundary in both library and
+CLI delivery, with accurate failure distinctions and documented permission limits.
 
 Additional forge implementations and compatibility claims belong to later work.
 Release preparation and publication continue under the