Feature/dsh contextforge bridge v1

CHANGELOG.md

@@ -8,6 +8,42 @@ and Python distribution versions follow PEP 440.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-24
+
+### Added
+
+- Added immutable, model-free repository discovery application contracts for
+  deterministic candidate preparation, read-only expansion, verified source
+  reads, and canonical context packaging.
+- Added the generic ContextForge bridge protocol v1 ADR, normative JSON Schema,
+  persistent workspace-bound JSON-RPC 2.0 service over bounded UTF-8 NDJSON
+  stdio, and a runnable generic client example.
+- Added explicit protocol negotiation and compatibility failures for missing or
+  unsupported v1 handshakes, cooperative JSON-RPC request cancellation, typed
+  source-identity drift, deterministic preparation/selection identities, and
+  bounded concurrent requests with serialized responses.
+- Added bridge architecture, CLI, troubleshooting, security, stream,
+  cancellation, read-only, repository-truth, and source-verification guidance.
+
+### Changed
+
+- Kept model-assisted discovery on the existing provider-backed path while
+  sharing its snapshot, mode, ranking, stale-index, path, and budget semantics
+  with the new public preparation API.
+- Stabilized the public model-free expansion DTO around closed operations and
+  explicit result fields. Removed the unused competing bridge envelope and
+  stopped JSON-RPC responses from serializing internal model actions, tool
+  names, steps, request echoes, or whole application DTOs.
+- Kept the read-only MCP server independent and unchanged while adding the
+  separate bridge transport.
+
+### Security
+
+- Defined bridge v1 as a trusted-local integration transport rather than an
+  authentication, sandbox, network, or multi-tenant boundary. The fixed
+  workspace permits verified reads only: no provider/network access, shell,
+  arbitrary subprocess, source/Git/index mutation, or disk artifact publish.
+
 ## [0.4.2.post1] - 2026-08-21
 
 ### Fixed

README.md

@@ -28,8 +28,8 @@ commands.
 </p>
 
 > [!IMPORTANT]
-> ContextForge is pre-alpha software. Version `0.4.2.post1` is the corrected
-> first public-release candidate. Discovery benchmarking is experimental and
+> ContextForge is pre-alpha software. Version `0.5.0` adds the stable generic
+> local bridge v1. Discovery benchmarking is experimental and
 > its results should be reviewed alongside the recorded provider, model,
 > configuration, and source snapshot.
 
@@ -183,12 +183,16 @@ mutating operations.
 | `contextforge diagnostics config [PATH]` | Explain effective configuration | Read-only |
 | `contextforge diagnostics provider [PATH]` | Show provider policy without probing it | Read-only |
 | `contextforge mcp serve [PATH]` | Run the local read-only stdio MCP server | Read-only session |
+| `contextforge bridge --stdio --workspace PATH` | Run persistent JSON-RPC bridge v1 | Verified read-only workspace session |
 | `contextforge benchmark discovery PATH` | Run manifest-driven discovery benchmarks | Repository/index read-only; experimental |
 
 Global diagnostic options are `--log-level`, `--log-format`, `--log-file`,
 repeatable `--log-component`, `--no-log-file`, `--no-color`, and `-v`/`-vv`.
 Detailed syntax, defaults, streams, side effects, mistakes, and examples are in
 the [Wiki CLI reference](https://github.com/waterflane/ContextForge/wiki/CLI-Overview).
+The local integration contract is documented in the
+[bridge v1 guide](docs/guides/bridge.md), with a runnable
+[generic client](examples/generic_bridge_client.py).
 
 ## Configuration
 

ROADMAP.md

@@ -60,15 +60,26 @@ This roadmap describes broad milestones only. It does not promise dates.
 - [ ] Publish the reviewed signed `v0.4.2.post1` release through TestPyPI and
   PyPI.
 
+## v0.5: Generic local integration bridge (release prepared)
+
+- [x] Expose immutable model-free candidate, expansion, verified-read, and
+  package application contracts without changing model-assisted discovery.
+- [x] Add a persistent workspace-bound JSON-RPC 2.0 bridge over UTF-8 NDJSON
+  stdio with explicit protocol v1 negotiation and cancellation.
+- [x] Keep repository truth, source identity verification, path policy, and
+  read-only guarantees inside ContextForge while consumers own model selection.
+- [x] Keep MCP independent and preserve its existing read-only protocol.
+- [ ] Publish or tag 0.5.0 after review and explicit release approval.
+
 ## Later
 
 - Full multi-root workspaces.
 - Additional deterministic language extractors based on measured demand.
 - Optional supplementary retrieval strategies that do not replace complete
   allowed-tree/text access.
 - Graphical workspace review UI.
-- External coding-agent integrations that consume handoffs under their own
-  authority.
+- Richer external integrations that consume bridge results and handoffs under
+  their own authority.
 
 Autonomous edits, coding-agent orchestration, Git worktree management, and Git
 mutation are not part of the current roadmap.

SECURITY.md

@@ -6,8 +6,8 @@ ContextForge is pre-1.0 software. Security fixes target the latest release.
 
 | Version | Supported |
 | --- | --- |
-| Latest `0.4.x` release | Yes |
-| `0.3.x` and earlier | No |
+| Latest `0.5.x` release | Yes |
+| `0.4.x` and earlier | No |
 
 ## Reporting a vulnerability
 
@@ -98,3 +98,22 @@ discovery executor as in-process callers. It advertises only read-only tools
 and resources: no sampling, remote transport, subscriptions, source/index
 mutation, shell/process execution, Git mutation, or agent orchestration.
 Protocol output is isolated on stdout; diagnostics use stderr.
+
+The ContextForge bridge is also a local stdio transport for trusted
+integrations, not a network service, sandbox, authorization layer, or
+multi-tenant boundary. The process inherits the invoking user's ability to read
+the bound workspace. Only launch clients you trust with repository excerpts,
+candidate metadata, index provenance, and context packages. Do not expose the
+bridge through a socket, web endpoint, shared pipe, privilege boundary, or
+untrusted process broker without adding authentication, authorization,
+isolation, and transport limits outside ContextForge.
+
+Bridge v1 is model-free and has no network, provider, shell, subprocess,
+source-write, Git-mutation, or index-mutation capability. Its package operation
+returns an in-memory artifact and does not publish a file. `snapshot`,
+`expected_snapshot_digest`, per-file SHA-256 identities, stable source reads,
+and `SOURCE_IDENTITY_CHANGED` prevent stale or substituted excerpts from being
+accepted as current repository truth. They detect changes; they do not turn a
+hostile same-account process into a safe peer. Stdout is reserved for bounded
+JSON-RPC frames and bounded diagnostics use stderr; both can contain sensitive
+repository-derived information and must be protected accordingly.

docs/RELEASE_CHECKLIST.md

@@ -35,13 +35,16 @@ uv run pytest
 uv build
 uv run twine check dist/*
 uv run check-wheel-contents dist/*.whl
+uv run python scripts/validate_distribution.py dist
 ```
 
 Inspect wheel and sdist contents. They may contain only package source,
 `pyproject.toml`, README, LICENSE, NOTICE, CHANGELOG, required packaging
 metadata, and Hatch's backend-required `.gitignore` build-control file. They
 must not contain tests, Wiki files, planning notes, GitHub metadata, caches,
-local state, logs, reports, credentials, or heavy images.
+local state, logs, reports, credentials, temporary bridge files, local paths,
+or development artifacts. Both archives must contain the complete
+`contextforge.bridge` package.
 
 Install the wheel and sdist in separate clean Python 3.12 and 3.13 environments.
 Verify only package metadata, importability, and version entry points:
@@ -51,8 +54,14 @@ python -c "import contextforge"
 contextforge --version
 ctxf --version
 python -m contextforge --version
+contextforge bridge --help
 ```
 
+Run an interactive subprocess smoke test that negotiates bridge protocol `1.0`,
+captures a real `snapshot`, and performs clean `shutdown`. Confirm every stdout
+line is JSON-RPC, stderr is separate, and the bound fixture workspace is byte-for-byte
+unchanged. Run the independent MCP stdio tests in the full pytest suite.
+
 Release validation must not require Ollama, LM Studio, a remote model API, an
 API server, or model-backed smoke tests. Tests use structural-only behavior or
 the deterministic fake provider.

docs/architecture/overview.md

@@ -27,6 +27,8 @@ The project is organized as a modular monolith with these boundaries:
 - `repositories`: repository and language analysis adapters;
 - `storage`: storage adapters;
 - `models`: model-provider adapters;
+- `bridge`: trusted-local JSON-RPC/NDJSON transport over the model-free
+  application boundary;
 - `cli`: command-line interface;
 - `api`: local HTTP API;
 - future IDE integrations outside the core.
@@ -61,7 +63,8 @@ a deterministic fake, and a local Ollama adapter. Incremental model-assisted
 [file and symbol semantic analysis](semantic-analysis.md) stores interpretations
 separately from source facts. Bounded hierarchical
 [repository architecture and feature maps](repository-maps.md) preserve the
-same facts-versus-interpretation boundary. Model-guided repository discovery is
+same facts-versus-interpretation boundary. Model-free and model-assisted
+repository discovery are
 documented in [Repository discovery](repository-discovery.md), and its
 review-to-package integration and pure prompt compiler are documented in
 [Context handoffs and prompt compilation](context-handoffs.md). ContextForge
@@ -75,7 +78,12 @@ decisions, request budgets, and causal errors for CLI and future interfaces
 without turning progress refreshes into logs. Thin Typer commands expose index and context workflows,
 while a bounded read-only MCP
 adapter exposes the same core APIs without shell, source-write, Git-mutation,
-or index-mutation capabilities.
+or index-mutation capabilities. The independent
+[generic bridge v1](../guides/bridge.md) is a second local stdio adapter. It
+binds one workspace, keeps repository truth and source verification inside
+ContextForge, and lets the consumer own model selection and orchestration. MCP
+and bridge do not depend on one another and neither introduces transport logic
+into the Python core.
 
 ## Excluded from v0.1.0
 
@@ -97,3 +105,5 @@ repository intelligence, bounded discovery, handoffs, and read-only MCP are
 implemented in v0.4. Version 0.4.1 adds maintenance-level progress,
 diagnostics, nested-ignore, and CLI usability improvements; it does not claim
 future GUI, remote transport, orchestration, or source-mutation functionality.
+Version 0.5.0 adds the trusted-local, model-free, read-only bridge v1 without
+changing the existing model-assisted discovery or MCP semantics.

docs/architecture/repository-discovery.md

@@ -1,4 +1,4 @@
-# Model-guided repository discovery
+# Repository discovery
 
 ## Implemented boundary
 
@@ -60,19 +60,48 @@ contracts are documented in the
 
 ## Public API
 
-The main entry point is asynchronous:
+The model-free application boundary exposes four synchronous operations over
+immutable DTOs:
+
+```python
+prepared = prepare_discovery_candidates(snapshot, request)
+expanded = expand_discovery(snapshot, prepared, expansion)
+verified = read_verified_context(snapshot, prepared, selection)
+package = package_verified_context(snapshot, verified)
+```
+
+Candidate preparation and expansion reuse the same mode-aware knowledge loader,
+ranking, path policy, budgets, index freshness checks, and verified source tools
+as model-assisted discovery. They never require or invoke a `ModelProvider`.
+Prepared and verified DTOs contain portable paths and source identities but no
+repository root, filesystem handle, mutable executor, or `DiscoverySession`.
+The public expansion DTO names a closed `operation` and returns explicit
+`ok`, `code`, `data`, truncation, progress, and budget fields. Internal
+model-assisted `action_id`, `tool_name`, step counters, and
+`DiscoveryObservation` objects do not cross this application boundary.
+
+The existing model-assisted entry point remains asynchronous:
 
 ```python
 record = await discover_repository(snapshot, provider, request)
 ```
 
 `DiscoverySession` exposes the same lifecycle for callers that need in-progress
-state. Core closed models include `DiscoveryRequest`, `DiscoveryMode`,
+state inside trusted Python integrations. It is not a bridge DTO. Core closed
+models include `DiscoveryRequest`, `DiscoveryMode`,
 `DiscoveryAction`, `DiscoveryObservation`, `DiscoveryState`, `DiscoveryBudget`,
 `DiscoveryCandidate`, `SelectionReason`, `FinalContextSelection`,
 `CompletenessWarning`, and `DiscoveryRunRecord`. Typed failures carry a run
 record whose `final_selection` is always absent.
 
+The trusted-local stdio adapter is described by
+[ADR-002](../decisions/002-generic-context-bridge-protocol-v1.md), the
+[bridge guide](../guides/bridge.md), and the
+[protocol v1 JSON Schema](../schemas/contextforge-bridge-v1.schema.json).
+JSON-RPC, NDJSON framing, protocol negotiation, concurrency, cancellation, and
+process lifetime remain entirely in `contextforge.bridge`, not in the
+application DTOs or discovery core.
+
 ## Tool and security boundary
 
 `DISCOVERY_TOOL_SCHEMAS` publishes closed input schemas for repository overview,