chore(wp7): hygiene, stubs, test/CI/tooling, doc gaps, boundary patterns doc

.pre-commit-config.yaml

@@ -28,12 +28,16 @@ ci:
   #     check-no-modify-migration:
   #     rebase / migration state checks meaningful only on the pushing
   #     developer's clone, not in an ephemeral cloud runner.
-  # ``no-release-please-token``, ``workflow-shell-git-commits``,
-  # ``no-review-origin-in-code`` and ``no-migration-framing`` are
-  # deliberately NOT skipped: all four are pure-Python, zero-dependency
+  # ``no-release-please-token`` and ``workflow-shell-git-commits`` are
+  # deliberately NOT skipped: both are pure-Python, zero-dependency
   # scripts with no CI counterpart, and letting pre-commit.ci enforce
-  # them closes the gap where a PR from a contributor who skipped local
-  # hooks would otherwise introduce a regression unchecked.
+  # them at the pre-commit stage closes the gap where a PR from a
+  # contributor who skipped local hooks would otherwise introduce a
+  # regression unchecked. ``no-review-origin-in-code`` and
+  # ``no-migration-framing`` run at ``stages: [pre-push]`` (the
+  # local-only pre-push hook surface) so pre-commit.ci does not pick
+  # them up; their CI counterpart is the ``Lint`` job in ``ci.yml``
+  # which runs the same scripts on every PR.
   skip: [commitizen, gitleaks, hadolint-docker, caddy-validate, zizmor, no-em-dashes, no-redundant-timeout, mypy, pytest-unit, golangci-lint, go-vet, go-test, eslint-web, check-push-rebased, check-single-migration-per-pr, check-no-modify-migration, forbidden-literals, persistence-boundary, persistence-protocol-uniformity, dependency-inversion, provider-complete-chokepoint, no-new-logger-exception-str-exc, otlp-span-redaction, orphan-fixtures, doc-drift-counts, boundary-typed, setting-to-startup-trace, long-running-loop-kill-switch, list-pagination, domain-error-hierarchy, dead-api-endpoints, dual-backend-test-parity, schema-drift, no-magic-numbers, convention-gate-inventory, mcp-admin-guardrail, runtime-stats-freshness, dto-types-ts-in-sync]
 
 default_install_hook_types: [pre-commit, commit-msg, pre-push]
@@ -452,7 +456,12 @@ repos:
         # script / baseline) cannot bypass the check.
         files: ^(src/synthorg/.*\.py|scripts/check_domain_error_hierarchy\.py|scripts/domain_error_hierarchy_baseline\.txt|\.pre-commit-config\.yaml)$
         pass_filenames: false
-        stages: [pre-commit, pre-push]
+        # Full-repo AST walk: ~2.7s on every commit becomes noticeable
+        # on focused-edit cycles where a developer commits multiple
+        # times in a row. Move to pre-push so each commit stays
+        # interactive while the gate still fires before code leaves
+        # the machine.
+        stages: [pre-push]
 
       - id: no-controller-response-for-domain-errors
         name: no-controller-response-for-domain-errors gate (raise typed errors, never build local Response envelopes)
@@ -618,10 +627,11 @@ repos:
         # the script's internal allowlist would immediately skip.
         files: ^(src/synthorg/(?!persistence/(?:postgres|sqlite)/revisions/).*\.(py|sql)|tests/.*\.py|scripts/check_no_review_origin_in_code\.py|\.pre-commit-config\.yaml)$
         pass_filenames: false
-        # pre-commit covers pre-commit.ci (catches GitHub-UI edits and
-        # contributors who skip local hooks); pre-push remains the
-        # primary developer-machine enforcement point.
-        stages: [pre-commit, pre-push]
+        # Full-repo scan is ~14s wall-clock; running it on every commit
+        # made focused-edit cycles painful. pre-push still catches
+        # everything before code leaves the machine, and pre-commit.ci
+        # is a separate hook surface (uses its own stage selection).
+        stages: [pre-push]
 
       - id: no-migration-framing
         name: no migration / origin / phase-N framing in code
@@ -635,4 +645,6 @@ repos:
         # files the script's internal allowlist would immediately skip.
         files: ^(src/synthorg/(?!persistence/(?:postgres|sqlite)/revisions/).*\.(py|sql)|tests/.*\.py|scripts/check_no_migration_framing\.py|\.pre-commit-config\.yaml)$
         pass_filenames: false
-        stages: [pre-commit, pre-push]
+        # ~13s wall-clock on the full repo; same cost trade-off as
+        # no-review-origin-in-code above. Moved to pre-push.
+        stages: [pre-push]

CLAUDE.md

@@ -23,6 +23,7 @@ Web: see `web/CLAUDE.md`. CLI: see `cli/CLAUDE.md` (use `go -C cli`, never `cd c
 ```bash
 uv sync                                             # all deps
 uv sync --group docs                                # docs toolchain (zensical + D2)
+bash scripts/install_cli_tools.sh                   # one-time per-machine: golangci-lint only (CI installs separately; install d2 via docs/getting_started.md)
 uv run ruff check src/ tests/ --fix                 # lint + auto-fix
 uv run ruff format src/ tests/                      # format
 uv run mypy src/ tests/                             # strict type-check

cli/cmd/new.go

@@ -35,6 +35,15 @@ Available kinds:
   synthorg new controller ping`,
 	GroupID: "core",
 	Args:    cobra.NoArgs,
+	// Render the help text when the user runs ``synthorg new`` with no
+	// subcommand, then exit with the usage error code so the parent
+	// shell can detect that a kind/domain was required. Without the
+	// explicit ExitUsage, the bare ``synthorg new`` would print help
+	// and exit 0, indistinguishable from a successful operation.
+	RunE: func(cmd *cobra.Command, _ []string) error {
+		_ = cmd.Help()
+		return NewExitError(ExitUsage, nil)
+	},
 }
 
 var newServiceCmd = newKindCmd(scaffold.KindService, "service")

cli/cmd/start.go

@@ -83,7 +83,31 @@ func runStart(cmd *cobra.Command, _ []string) error {
 
 	state, err := config.Load(opts.DataDir)
 	if err != nil {
-		return fmt.Errorf("loading config: %w", err)
+		// config.Load(...) returns DefaultState silently when the file
+		// is absent, so a non-nil error here means the file exists but
+		// is unreadable, malformed, or fails schema validation.
+		// Distinguish each shape via typed sentinels so the operator
+		// knows whether to repair the file or check permissions
+		// instead of guessing from a generic ``loading config:``
+		// wrapper.
+		switch {
+		case errors.Is(err, config.ErrParsing):
+			return fmt.Errorf(
+				"config file is malformed (invalid JSON); "+
+					"edit it manually or remove it and re-run "+
+					"'synthorg init': %w", err,
+			)
+		case errors.Is(err, config.ErrReading):
+			return fmt.Errorf(
+				"config file is unreadable (check filesystem "+
+					"permissions): %w", err,
+			)
+		default:
+			// Anything else (validation / DataDir canonicalisation) is
+			// surfaced as-is with a ``config:`` prefix so the operator
+			// reads the wrapped detail directly.
+			return fmt.Errorf("config: %w", err)
+		}
 	}
 	safeDir, err := safeStateDir(state)
 	if err != nil {

cli/cmd/update.go

@@ -105,9 +105,11 @@ func runUpdate(cmd *cobra.Command, _ []string) error {
 
 	// CLI update (unless --images-only).
 	if !updateImagesOnly {
-		if err := updateCLI(cmd, state.AutoUpdateCLI); errors.Is(err, errReexec) {
+		err := updateCLI(cmd, state.AutoUpdateCLI)
+		if errors.Is(err, errReexec) {
 			return reexecUpdate(cmd)
-		} else if err != nil {
+		}
+		if err != nil {
 			return fmt.Errorf("updating CLI binary: %w", err)
 		}
 	}
@@ -235,6 +237,16 @@ func downloadAndApplyCLI(ctx context.Context, out *ui.UI, result selfupdate.Chec
 		return nil
 	}
 
+	// Surface a permission error in the install directory before the
+	// download starts; otherwise the user waits through a multi-MB
+	// transfer only to fail at the final ``Replace`` step.
+	if err := selfupdate.ProbeInstallDirWritable(); err != nil {
+		return fmt.Errorf(
+			"cannot update CLI in place; re-run as an administrator "+
+				"or move the binary to a writable directory: %w", err,
+		)
+	}
+
 	out.Step("Downloading...")
 	binary, err := selfupdate.Download(ctx, result.AssetURL, result.ChecksumURL, result.SigstoreBundURL)
 	if err != nil {

cli/internal/config/state.go

@@ -18,6 +18,19 @@ import (
 
 const stateFileName = "config.json"
 
+// Sentinel errors for Load failure modes, classified so callers can
+// branch on shape (errors.Is) rather than on error.Error() prefix. The
+// shapes are mutually exclusive: at most one wraps any given Load
+// error.
+var (
+	// ErrReading is wrapped when the persisted config file exists but
+	// cannot be read (filesystem permissions, I/O error, etc.).
+	ErrReading = errors.New("reading config")
+	// ErrParsing is wrapped when the config file is present and
+	// readable but its bytes do not decode as valid JSON.
+	ErrParsing = errors.New("parsing config")
+)
+
 // Fine-tune variant identifiers persisted in State.FineTuningVariant and
 // used to construct image service names (e.g. "synthorg-fine-tune-gpu").
 const (
@@ -267,12 +280,12 @@ func Load(dataDir string) (State, error) {
 			defaults.Sandbox = false
 			return defaults, nil
 		}
-		return State{}, fmt.Errorf("reading config %s: %w", path, err)
+		return State{}, fmt.Errorf("%w %s: %w", ErrReading, path, err)
 	}
 	// Unmarshal onto defaults so missing fields retain default values.
 	s := DefaultState()
 	if err := json.Unmarshal(data, &s); err != nil {
-		return State{}, fmt.Errorf("parsing config %s: %w", path, err)
+		return State{}, fmt.Errorf("%w %s: %w", ErrParsing, path, err)
 	}
 	if err := s.validate(); err != nil {
 		return State{}, fmt.Errorf("config %s: %w", path, err)

cli/internal/selfupdate/updater.go

@@ -512,6 +512,43 @@ func Replace(binaryData []byte) error {
 	return ReplaceAt(binaryData, execPath)
 }
 
+// ProbeInstallDirWritable verifies the directory holding the current
+// executable is writable BEFORE a download is started. The probe
+// creates and removes a short-named tempfile so a permission error
+// surfaces in microseconds instead of after the user has already
+// waited through a multi-MB download. Returns nil when writable.
+func ProbeInstallDirWritable() error {
+	execPath, err := os.Executable()
+	if err != nil {
+		return fmt.Errorf("finding executable path: %w", err)
+	}
+	return ProbeInstallDirWritableAt(execPath)
+}
+
+// ProbeInstallDirWritableAt is the testable core of
+// ProbeInstallDirWritable: it accepts the executable path explicitly
+// so unit tests can target an arbitrary directory.
+func ProbeInstallDirWritableAt(execPath string) error {
+	resolved, err := filepath.EvalSymlinks(execPath)
+	if err != nil {
+		return fmt.Errorf("resolving symlinks for write probe: %w", err)
+	}
+	dir := filepath.Dir(resolved)
+	f, err := os.CreateTemp(dir, ".synthorg-write-probe.*.tmp")
+	if err != nil {
+		return fmt.Errorf("install directory %s is not writable: %w", dir, err)
+	}
+	tmpPath := f.Name()
+	if cerr := f.Close(); cerr != nil {
+		_ = os.Remove(tmpPath)
+		return fmt.Errorf("closing write-probe file: %w", cerr)
+	}
+	if rerr := os.Remove(tmpPath); rerr != nil {
+		return fmt.Errorf("removing write-probe file %s: %w", tmpPath, rerr)
+	}
+	return nil
+}
+
 // ReplaceAt swaps the binary at the given path with new content.
 // This is the testable core of Replace.
 func ReplaceAt(binaryData []byte, execPath string) error {

docs/architecture/decisions.md

@@ -129,6 +129,13 @@ All significant design and architecture decisions in force today, organized by d
 
 **Mitigation plan:** (1) File upstream PR against `nats-io/nats.py` with the one-line `inspect.iscoroutinefunction` fix; upstream PR status is tracked in the project issue queue (search `nats-py` label); the scoped `filterwarnings` entry in `pyproject.toml` remains the active workaround until a fixed upstream release is available. (2) If upstream is unresponsive by **2026-06-10** (60 days from the 2026-04-11 review), maintain a local monkey-patch in `bus/_nats_compat.py`. (3) Monitor `nats-core` for future JetStream support.
 
+**Verification checkpoint (2026-06-10):** on this date run the checklist below and update this section with the outcome (mark each item Done / Not done / Outcome).
+
+1. Inspect `nats-io/nats.py` open PRs and recent releases on GitHub for the `inspect.iscoroutinefunction` fix.
+2. If a fixed release is available: bump the `nats-py` pin in `pyproject.toml`, drop the matching `filterwarnings` entry, run `uv run python -m pytest tests/ -m integration -k nats` to confirm warnings are gone, and replace this checkpoint section with the resolution outcome.
+3. If no fixed release exists: implement the local monkey-patch in `src/synthorg/communication/bus/_nats_compat.py` (one-line `nats.aio.client.iscoroutinefunction = inspect.iscoroutinefunction`), import it at bus initialisation, and extend this section with the patch landing date.
+4. Re-evaluate `nats-core` JetStream support: a maintained alternative removes the entire mitigation requirement.
+
 ## Overarching Pattern
 
 Nearly every decision follows the same architecture: a pluggable protocol interface with one initial implementation shipped, and alternative strategies documented for future extension. This is consistent with the project's protocol-driven design philosophy.

docs/getting_started.md

@@ -32,6 +32,26 @@ uv sync
 
 `uv sync` creates a virtual environment in `.venv/` and installs all development dependencies (linters, type checker, test runner, pre-commit, etc.).
 
+## Install external CLI tools (one-time per machine)
+
+Some gates and the docs build rely on external binaries that are not Python packages: `golangci-lint` (Go linter, used by the CLI) and `d2` (architecture diagram renderer).
+
+Install `golangci-lint` once per machine:
+
+```bash
+bash scripts/install_cli_tools.sh
+```
+
+The script downloads the pinned `golangci-lint` version that matches CI (`.github/workflows/cli.yml`). Re-run only after bumping the pinned version; subsequent `uv sync` invocations do NOT re-run the script. CI uses its own action-based install step, so this is strictly a local-developer convenience.
+
+Install `d2` separately (the docs job pins `v0.7.1`). The fastest path is the upstream installer:
+
+```bash
+curl -fsSL https://d2lang.com/install.sh | sh -s -- --version v0.7.1
+```
+
+On Windows, install via `winget install Terrastruct.d2` or download the release archive from `https://github.com/terrastruct/d2/releases`. Either way, ensure the resulting `d2` binary is on `PATH`; the docs build invokes it directly.
+
 ## Verify Installation
 
 Run the smoke tests to confirm everything is working:

docs/guides/a2a-federation.md

@@ -0,0 +1,112 @@
+---
+title: A2A Federation
+description: Register a peer SynthOrg deployment, expose JSON-RPC methods, route tasks across the federation.
+---
+
+# A2A Federation
+
+The Agent-to-Agent (A2A) bridge lets one SynthOrg deployment delegate tasks to a peer over JSON-RPC. Each side authenticates with a shared JWT credential and the typed boundary at `synthorg.a2a.rpc_params.parse_rpc_params` validates every inbound `params` block. This guide walks through registering a peer, enabling specific RPC methods, and observing a federation round-trip.
+
+## Concepts
+
+- **Peer**: a SynthOrg deployment reachable at an HTTPS URL with a JSON-RPC endpoint mounted at `/a2a`.
+- **Method**: a JSON-RPC operation the gateway exposes. The current method set is `message/send`, `tasks/get`, and `tasks/cancel`.
+- **Envelope precedence**: the JSON-RPC `method` field on the envelope always wins; a `method` key smuggled inside `params` is rejected at `parse_rpc_params` time.
+
+## Configuration surface
+
+Settings live under the `a2a` namespace. Resolve them via `SettingsService` or set them in the company-template YAML.
+
+| Key | Type | Default | Purpose |
+|---|---|---|---|
+| `a2a.enabled` | bool | `false` | Master switch for the federation gateway. |
+| `a2a.peer_url` | URL | (unset) | Outbound peer endpoint. |
+| `a2a.peer_jwt_secret` | secret | (unset) | HMAC key for outbound JWT. |
+| `a2a.methods_enabled` | list[str] | `[]` | Allowlist of inbound methods. |
+| `a2a.timeout_seconds` | float | `30` | Per-request wall-clock budget. |
+
+## Worked example: two-node round-trip
+
+The example uses two local processes on ports `8000` (node A) and `8001` (node B); each side has the other registered as its peer.
+
+### Node B (callee)
+
+```bash
+SYNTHORG_DATA_DIR=/tmp/synthorg-b \
+  SYNTHORG_BACKEND_PORT=8001 \
+  uv run python -m synthorg.api
+```
+
+```yaml
+# /tmp/synthorg-b/config.yaml
+a2a:
+  enabled: true
+  methods_enabled:
+    - tasks/get
+  peer_jwt_secret: "shared-secret-do-not-commit"
+```
+
+### Node A (caller)
+
+```yaml
+# /tmp/synthorg-a/config.yaml
+a2a:
+  enabled: true
+  peer_url: http://localhost:8001/a2a
+  peer_jwt_secret: "shared-secret-do-not-commit"
+  methods_enabled: []
+```
+
+Call `tasks/get` from node A:
+
+```python
+import httpx
+import jwt
+import uuid
+
+token = jwt.encode({"sub": "synthorg-a", "aud": "synthorg-b"}, "shared-secret-do-not-commit", algorithm="HS256")
+
+payload = {
+    "jsonrpc": "2.0",
+    "id": str(uuid.uuid4()),
+    "method": "tasks/get",
+    "params": {"task_id": "task-12345"},
+}
+resp = httpx.post(
+    "http://localhost:8001/a2a",
+    json=payload,
+    headers={"Authorization": f"Bearer {token}"},
+)
+print(resp.json())
+```
+
+Expected outcomes:
+
+- `200` with a `result` block when the task exists.
+- `404` (mapped to JSON-RPC error `-32602` with `data.code: "task_not_found"`) when the task is unknown.
+- `403` when the bearer JWT does not validate (peer secret mismatch or `aud` claim incorrect).
+
+## Observability
+
+Every inbound JSON-RPC call emits these events:
+
+- `a2a.jsonrpc.received`: at envelope decode; carries `peer`, `method`, `id`.
+- `api.boundary.validation_failed`: when `parse_rpc_params` rejects a malformed `params` block.
+- `a2a.jsonrpc.dispatched`: at successful method dispatch.
+- `a2a.jsonrpc.error`: at error path (with `code` and `message`).
+
+The `a2a.dispatch_latency_seconds` histogram has a `method` label so per-RPC latency is easy to chart.
+
+## Threat model + extension
+
+The boundary check is the only validation gate; downstream handlers MUST treat their typed `params` as already-validated.
+
+To add a new method:
+
+1. Define an `A2A<Method>Params` Pydantic model under `src/synthorg/a2a/rpc_params.py`.
+2. Add it to the `A2ARpcParams` discriminated union.
+3. Register the handler in the gateway registry.
+4. Add the method name to the per-peer `a2a.methods_enabled` allowlist.
+5. Cover the wire shape in `tests/unit/a2a/test_<method>.py`.
+
+See [docs/reference/typed-boundaries.md](../reference/typed-boundaries.md) for the boundary contract and [docs/design/a2a.md](../design/a2a.md) for the full protocol design.