deepdebug-local-agent 1.0.22 → 1.1.0

package/.claude/context.md

@@ -0,0 +1,76 @@
+# deepdebug-local-agent: context for AI agents
+
+> Read this, then `.claude/standards/` (`node.md` for this stack), then `README.md`.
+
+## What this repo is
+
+The platform's **hands inside the customer's infrastructure**: a Node.js (ESM, Node 18+)
+agent that watches application logs, detects errors and forwards incidents, serves the
+workspace (file tree, reads, patches, git, exec) to the platform, keeps a WebSocket
+reverse tunnel to the gateway, exposes an MCP bridge, and ships legacy-stack connectors
+(SAP, IBM MQ, AS/400, Oracle Forms, COBOL; opt-in through `LEGACY_STACKS`).
+
+Distributed as the npm package `deepdebug-local-agent` (published from `main`) and as a
+Cloud Run service (`deepdebug-local-agent-qa` / `deepdebug-local-agent`) for the hosted
+variant.
+
+**Does not:** call LLMs or hold provider keys (the thinking happens in vh-agents via
+vh-litellm), decide tenant policy, or merge anything.
+
+## Neighbours
+
+```
+customer apps/logs --> [local-agent] --HTTP /api/v1/internal/incident/create, /api/v1/agent/authorize--> vh-api-gateway
+                        [local-agent] <==WS tunnel /api/v1/agent/ws==> vh-api-gateway <--> vh-agents
+                        [local-agent] --MCP bridge (5056)-- local tools;  git providers (GitHub/Bitbucket) for multi-repo PRs
+```
+The gateway base URL comes from `GATEWAY_URL` / `~/.deepdebug/config.json`. For QA use
+`https://api-qa.visionhammer.io`, not the `*-575662086506.run.app` URLs in old notes,
+which are dead.
+
+## Where things live
+
+| Path | What |
+|---|---|
+| `src/server.js` | main Express server (very large; extract new code into modules) |
+| `src/routes/` | route modules (`workspace.route.js`) |
+| `src/workspace/`, `src/utils/` | scanning, file reads, process manager, multi-repo open, open gate, sandbox, path helpers |
+| `src/patch/`, `patch-manager.js` | patch engine and backups |
+| `src/git/` | git providers, multi-repo PRs |
+| `src/siblings/` | incident forwarder, burst suppressor, capabilities, logger, metrics |
+| `src/adapters/` | legacy-stack connectors (fixed 6-key error shape) |
+| `src/mcp-http-server.js` | MCP HTTP bridge |
+| `test/` | `node:test` suites plus fixtures |
+| `bin/install.js`, `helm/`, `Dockerfile*` | install and packaging |
+
+## Run and test
+
+```bash
+npm install
+npm test          # node --test
+npm start         # port 5055, MCP bridge on 5056
+```
+
+## Deploy and rollback
+
+- PR to **`main`**. Merging to `main` with changes under `src/`, `bin/` or `package.json`
+  **publishes the npm package** (`npm-publish.yml`), so bump the version deliberately.
+  Customers pick it up on install or update.
+- Cloud Run deploy is **manual** (`deploy-gcp.yml`, `workflow_dispatch`, pick `qa` or
+  `prod`).
+- Rollback: npm, by publishing a fixed patch version (don't unpublish); Cloud Run, via
+  `update-traffic` to the revision that was serving (read it live, with percentages).
+
+## Gotchas that matter here
+
+- Runs with the customer's privileges: every exec is an argument array with a confined
+  `cwd`; every path is confined to the workspace; branch and ref names are validated
+  (`branch-refspec.js`).
+- Customer logs contain secrets and PII: redact before forwarding; never log
+  `DEEPDEBUG_API_KEY`, tokens or credentialed git URLs.
+- Tenant identity comes from the agent's registration and token, verified by the
+  gateway. Never trust a tenant id sent by a remote caller.
+- `CLAUDE_CODE_AGENT_INFINITE.md` and similar root notes are **historical**. They
+  reference the dead `insptechai` project, dead hosts and inline credentials. Do not run
+  them or copy values from them.
+- Committed tarballs (`local-agent-source.tar.gz`) are build leftovers; don't add more.

package/.claude/skills/README.md

@@ -0,0 +1,25 @@
+# Project skills
+
+Claude Code skills copied verbatim from the team's `programming-skills` collection
+(`programming-skills/skills/<name>/`, June 2026 snapshot). Each one is loaded on demand
+when its `description` matches the task.
+
+| Skill | Use for |
+|---|---|
+| `tdd-debugging` | proving a bug with a failing test before fixing it (Java, Python and Node commands) |
+
+Only language-neutral skills were copied here. The rest of the collection is Java/Spring
+specific (the gateway and vh-agents carry those). The shared rules for this repo's stack
+are in `.claude/standards/`.
+
+**Precedence:** where a skill disagrees with `CLAUDE.md`, `.claude/context.md` or
+`.claude/standards/`, the repo files win.
+
+## Licence and provenance
+
+The `programming-skills` collection has **no LICENSE file**. `skill-creator` describes it
+as the VisionHammer programming-skills repository, and part of it looks adapted from an
+external collection whose origin is not recorded. Treat these files as internal. **Do not
+publish or redistribute them** (this matters for the Forge app, which may ship to the
+Marketplace; `.claude/` is not part of the Forge bundle) until provenance and licence are
+confirmed.

package/.claude/skills/tdd-debugging/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: tdd-debugging
+description: >
+  Fix production bugs by proving them with a failing test before changing code.
+  Preserve existing tests as immutable evidence. Workflow: RED -> GREEN ->
+  REFACTOR across Java, Python, and Node.js.
+argument-hint: [bug-description]
+allowed-tools: Read Grep Bash
+---
+
+## When to Use
+
+Use `tdd-debugging` for bugs or regressions that require a proof-of-failure test.
+Use [test-quality](../test-quality/SKILL.md) for test design, flakiness, or general coverage issues.
+
+## Core Rules
+
+1. **Existing tests are sacred.** Never modify or delete an existing test to make the suite pass.
+2. **Prove RED first.** If tests pass but the bug exists, add a new regression test that fails before the fix.
+3. **Keep it narrow.** One bug, one scenario, one assertion focus.
+4. **No side effects.** Report technically broken tests (dead endpoints, etc.) before changing them.
+5. **Verify in stages.** Targeted test -> Module suite -> Full project suite.
+
+## Workflow
+
+### Phase 1: RED
+1. Extract failing behavior from report/stack trace.
+2. Detect nearest module (look for `pom.xml`, `build.gradle`, `pyproject.toml`, `package.json`).
+3. Run relevant existing tests. If one fails, use it as proof. If all pass, add a new one.
+4. **Heuristics for new tests**: focus on null/missing input, boundary values, invalid state transitions, or wrong exception types.
+
+### Phase 2: GREEN
+1. Patch production code to satisfy the failing scenario.
+2. Re-run targeted test until it passes.
+3. Run local module suite to check for immediate regressions.
+
+### Phase 3: REFACTOR
+1. Run full project suite.
+2. Verify all tests pass, including the new or formerly failing proof test.
+3. Summarize: scenario, regression proof, patch, and validation results.
+
+## References
+- [command-reference.md](./references/command-reference.md): essential commands by stack.
+- [anti-patterns.md](./references/anti-patterns.md): critical mistakes to avoid.
+
+## Response Format
+Include:
+1. **Scenario**: Bug description and proof type (existing vs new).
+2. **Regression Proof**: Name of failing test kept unchanged or added.
+3. **Patch**: Summary of production code changes.
+4. **Validation**: Results for targeted test, module suite, and full suite.
+5. **Existing tests modified**: `0`
+

package/.claude/skills/tdd-debugging/references/anti-patterns.md

@@ -0,0 +1,43 @@
+# TDD Debugging Anti-Patterns
+
+Avoid these failure modes to ensure debugging reliability.
+
+## Critical Mistakes
+
+- **Modifying existing tests to force success**: This destroys your only baseline evidence. Existing tests must remain unchanged as proof of the regression.
+- **Deleting failing tests**: A failing test is your "RED" proof. Deleting it makes the fix unverified.
+- **Changing production code before RED**: If you don't see the test fail first, you haven't proven that your test actually covers the bug.
+- **Swallowing exceptions**: Using generic `catch (Exception e)` or empty catch blocks hides the root cause and makes future debugging harder.
+- **Using try/catch for control flow in a fix**: This often masks the symptom instead of fixing the logic error.
+- **Asserting internal implementation details**: Avoid mocking private methods or checking internal call order if an externally visible behavior assertion is possible. This makes tests brittle.
+- **Leaving debug leftovers**: Hardcoded values, `print` statements, or temporary branches must be removed before the "REFACTOR" phase is complete.
+
+## Canonical Example: Preserving Evidence
+
+Bad (Rewriting the evidence):
+
+```java
+@Test
+void shouldFindUser() {
+    User user = userService.findById(1L); // changed from null to force success
+    assertNotNull(user);
+}
+```
+
+Good (Preserving the proof and adding a fix):
+
+```java
+@Test
+void shouldFindUser() {
+    User user = userService.findById(null); // unchanged failing proof
+    assertNotNull(user);
+}
+
+@Test
+void shouldRejectNullId() {
+    assertThatThrownBy(() -> userService.findById(null))
+        .isInstanceOf(IllegalArgumentException.class);
+}
+```
+
+**Why this matters**: Changing the input in an existing test to make it pass hides the fact that the original code couldn't handle the edge case. Always add a new test for missing coverage.

package/.claude/skills/tdd-debugging/references/command-reference.md

@@ -0,0 +1,46 @@
+# Essential Command Reference
+
+Prefer the smallest command that proves the bug. Run from the module directory first.
+
+## Module Detection
+
+Locate the nearest build file:
+- **Maven**: `pom.xml`
+- **Gradle**: `build.gradle` or `build.gradle.kts`
+- **Python**: `pyproject.toml`
+- **Node.js**: `package.json`
+
+## Test Execution by Stack
+
+### Maven
+```bash
+mvn test -Dtest=ClassName                    # Run specific test class
+mvn test -Dtest=ClassName#methodName         # Run specific test method
+mvn test -pl :module-name                    # Run module from root
+```
+
+### Gradle
+```bash
+./gradlew test --tests ClassName             # Run specific test class
+./gradlew test --tests ClassName.methodName  # Run specific test method
+./gradlew :module-path:test                  # Run module from root
+```
+
+### Python (pytest)
+```bash
+pytest path/to/test_file.py                  # Run specific file
+pytest path/to/test_file.py::test_name       # Run specific test
+```
+
+### Node.js (npm/jest)
+```bash
+npm test -- FileName                         # Run specific file
+npm test -- -t "test name"                   # Run specific test
+```
+
+## Git Triage
+
+Use only when the bug is hard to localize:
+- `git show <commit> -- <file>`: Inspect recent changes to a specific file.
+- `git blame -L <start>,<end> <file>`: Identify when a specific line changed.
+- `git bisect`: Automate finding the commit that introduced a regression.

package/.claude/standards/README.md

@@ -0,0 +1,51 @@
+# VisionHammer engineering standards
+
+These files are the same in every VisionHammer repo. Every AI coding agent (Claude Code,
+Cursor, Copilot, Codex, Gemini) and every human contributor follows them. Repo-specific
+facts, such as what the repo is, how to run it and its gotchas, live in `.claude/context.md`.
+Repo rules in `CLAUDE.md` / `AGENTS.md` win over anything here.
+
+| File | Use it when |
+|---|---|
+| [clean-code.md](clean-code.md) | naming, method size, comments, errors, local readability |
+| [solid.md](solid.md) | splitting classes, adding variants, choosing abstractions |
+| [simplicity.md](simplicity.md) | before adding any abstraction, flag, option or dependency |
+| [layered-architecture.md](layered-architecture.md) | placing new code; feature/layer boundaries; ports |
+| [security-owasp.md](security-owasp.md) | every endpoint, input, secret, outbound call, log line |
+| [testing.md](testing.md) | writing or reviewing tests; proving a fix |
+| [code-review-checklist.md](code-review-checklist.md) | before opening a PR and when reviewing one |
+| [java-spring.md](java-spring.md) | Java 17+/21, Spring Boot WebFlux, Reactor, R2DBC (gateway, agents) |
+| [typescript-react.md](typescript-react.md) | TypeScript, React, Vite, Forge UI Kit (frontend, forge app) |
+| [python.md](python.md) | Python 3.12 (codescan, vh-litellm plugins) |
+| [node.md](node.md) | plain JavaScript on Node.js, ESM (deepdebug-local-agent) |
+
+A repo only ships the language files for its own stack.
+
+## Standards the build enforces
+
+A rule that no test enforces is a wish. These guard tests fail the build. **Never widen an
+allowlist or a baseline to make one pass. Fix the code.**
+
+| Guard test | Repo | What it enforces |
+|---|---|---|
+| `LayeredArchitectureTest` | vh-api-gateway | ADR-002: in the `LAYERED_FEATURES` features, the domain is framework-free, `api` never reaches `infrastructure`, `application` never depends on `api`/`infrastructure`, and features talk only through `application` |
+| `LlmAgnosticRatchetTest` | vh-api-gateway | ADR-001: no new class or file couples to an LLM provider, router or model id. The baselines in `src/test/resources/architecture/` only shrink |
+| `ControllerTenantSourceArchTest` | vh-api-gateway | a controller never takes `tenantId` from the body, query or path, and never falls back to client input. The tenant comes only from `TenantAccessGuard` |
+| `SecretsNeverReachLogsTest` | vh-api-gateway | credentials in URLs are redacted before logging, and decrypted secrets never hit a logger |
+| `AutomationGateArchTest` | vh-api-gateway, orchestrator | every path that can apply a patch goes through `AutomationGateService` |
+| `NoAutonomousMergeArchitectureTest` | vh-api-gateway, vh-agents | nothing merges a PR except the human approval path (`PrApprovalService.approve`) |
+| `NoDirectProviderCallsGuardTest` | vh-agents | no provider SDK, host or key outside the LiteLLM adapter package |
+| `EgressUrlGuardTest`, `NoEcbEncryptionArchTest`, `QaProfileArchTest` | vh-api-gateway | SSRF guard on tenant URLs; no AES/ECB and no fail-open decrypt; QA-only beans stay `@Profile("qa")` |
+| `tests/test_no_direct_provider.py` | codescan | no provider SDK or host outside `src/llm/litellm.py` |
+| `tests/test_config_loads.py`, `tests/test_smart_router.py` | vh-litellm | every alias has a `residency_class`; no fallback crosses a class; tier routing |
+
+If you add a rule that matters, add the guard that enforces it in the same PR.
+
+## Where this came from
+
+This is distilled and rewritten from the team's `programming-skills` collection:
+`clean-code`, `solid-principles`, `architecture-review`, `security-audit`, `test-quality`,
+`tdd-debugging`, `java-guidelines`, `reactive-webflux`, `r2dbc-patterns`, `logging-patterns`
+and `multi-tenant-saas`, then corrected against the v2 architecture (ADR-001..003) and the
+code as it is. Where the source skills disagree with our code, these files follow the code.
+One example: cross-tenant access answers **404**, not 403.

package/.claude/standards/clean-code.md

@@ -0,0 +1,75 @@
+# Clean code
+
+Aim: someone new to the code understands a change in one read. Keep behaviour stable and
+prefer the smallest change that makes the code easier to read, name, test and change.
+
+## Names
+
+- Name things in the domain's words: `IncidentFixRunner`, `resolveWorkspaceForTenant`,
+  `allowedTiers`. Avoid `data`, `info`, `manager`, `helper`, `util`, `process`, `handle`
+  used on its own.
+- Booleans read as questions: `isEnabled`, `hasRepo`, `canAutoMerge`, `shouldRetry`.
+- A method named `validateAndSaveAndNotify` does three things. Split it.
+- Spell words out. Only use well-known acronyms (`URL`, `JWT`, `DTO`, `SSE`, `PR`).
+- One concept, one word, across all repos. Tenant, workspace, incident and scan mean the
+  same thing everywhere; don't mix in synonyms like "org", "project" or "ticket" for them.
+
+## Functions
+
+- A function does one thing at one level of abstraction. Keep orchestration ("load, check,
+  act, emit") apart from the details of each step.
+- Use guard clauses so the main path isn't buried under nesting:
+
+  ```java
+  if (workspace == null) return Mono.error(new WorkspaceNotFoundException(id));
+  if (!workspace.isActive()) return Mono.empty();
+  return runScan(workspace);
+  ```
+- More than 3 or 4 parameters, or a `boolean` that changes behaviour: use a parameter
+  object, a record or an enum (`ScanMode.FULL`, not `run(repo, true)`).
+- No hidden side effects. A method called `get*` or `is*` must not write, publish or
+  mutate state.
+
+## Literals and types
+
+- Give magic numbers and strings a name (`MAX_ITERATIONS = 15`, `CALLBACK_TTL`).
+- Use a value object or enum when mixing primitives up is a real risk (tenant id vs
+  workspace id, both `UUID`).
+- Keep units in names or types: `timeoutMs`, `Duration timeout`.
+
+## Comments
+
+- A comment explains **why**: a constraint, an incident, an ordering requirement, a link
+  to an ADR. It never narrates what the code does.
+  ```java
+  // 404, not 403: a 403 confirms the id exists (TenantAccessGuard javadoc).
+  ```
+- If you need a comment to explain *what*, rename or extract first.
+- Delete dead code. Don't comment it out and don't hide it behind a flag "just in case".
+  Git remembers it. (Gateway: removals follow CLAUDE.md rule 1.)
+- Keep TODOs to a minimum. Each one says what, why and who or which ticket.
+
+## Errors
+
+- Don't use exceptions for normal control flow.
+- Never swallow an error. Log it with context, or propagate it, or both at one boundary,
+  not at every layer.
+- When wrapping an exception, keep the cause: `new ScanFailedException("trivy", e)`.
+- Fail closed. Missing config, a secret you can't read or a check that errors means deny,
+  not allow.
+
+## Duplication
+
+- DRY applies to **knowledge**, not to lines that happen to look alike. Two blocks that
+  will change for different reasons can stay separate.
+- Extract only once the third copy shows up, or once the first copy has a bug you had to
+  fix twice.
+
+## Do / don't
+
+| Do | Don't |
+|---|---|
+| Rename, extract, add guard clauses in their own commit | Mix a refactor with a behaviour change in one commit |
+| Prefer linear code in small orchestration classes | Add a generic helper that forces readers to jump across files |
+| Keep a method's inputs and outputs explicit | Communicate through mutable fields or `ThreadLocal` |
+| Leave the file cleaner than you found it (small, local) | Reformat whole files you are not otherwise changing |

package/.claude/standards/code-review-checklist.md

@@ -0,0 +1,61 @@
+# Code review checklist
+
+Use it on your own diff before opening the PR, and on others' PRs. Report findings by
+severity, with a file and line and the smallest fix. If nothing is wrong, say what you did
+**not** verify.
+
+## Blockers (must fix before merge)
+
+- [ ] **Tenant:** the tenant comes from the JWT (`TenantAccessGuard`), never the client;
+      every lookup by id checks ownership; foreign ids answer 404; there is a
+      cross-tenant test.
+- [ ] **Secrets:** nothing secret in code, config, tests, logs, errors or the PR body; no
+      provider key outside vh-litellm; env changes use `--update-*`.
+- [ ] **LLM boundary:** no model id, provider host, provider SDK or router outside
+      vh-litellm / the LiteLLM adapter; the gateway calls agents through `agenttask` ports
+      only.
+- [ ] **Automation:** anything that applies patches goes through `AutomationGateService`;
+      no new merge path; agents stop at "PR opened".
+- [ ] **Internal endpoints:** internal bearer via `InternalTokenAuthenticator`
+      (constant-time, fail closed), or a per-purpose token (HMAC callback).
+- [ ] **Input:** validated at the boundary; SQL is parameterized; shell and git use
+      argument arrays; paths are confined; URLs pass the egress guard.
+- [ ] **Schema:** changes only through a versioned migration; no runtime DDL; new column
+      writes are tested against real Postgres.
+- [ ] **Guards green:** no allowlist or baseline widened to pass. Baselines only shrink.
+- [ ] **Java:** ASCII only (`LC_ALL=C grep -n '[^ -~]' $(git ls-files '*.java')`); no
+      `.block()` on Netty threads.
+
+## Design
+
+- [ ] New code lives in the right feature and layer; dependencies point inward; no new
+      code in the legacy `service/` or `controller/` tree.
+- [ ] One intent per PR; mechanical moves, removals and behaviour changes are separate.
+- [ ] No speculative abstraction, flag or dependency (`simplicity.md`). Every new flag has
+      an owner and an exit condition.
+- [ ] Contracts between repos (FE routes, `/api/v2` DTOs, codescan result schema, Forge
+      gateway contract) are changed on both sides, or stay backward compatible.
+- [ ] Consumers were checked by grepping the other repos, not assumed from javadoc.
+
+## Readability
+
+- [ ] Names in domain words; functions do one thing; guard clauses; no magic values.
+- [ ] Comments explain why; no commented-out code; no stray debug output (`console.log`,
+      `print`, `System.out`).
+- [ ] Errors are propagated or logged once, with context and cause.
+
+## Tests
+
+- [ ] Behaviour and scenarios covered (happy, edge, invalid, error, auth, cross-tenant).
+- [ ] A bug fix has a test that failed before the fix.
+- [ ] No existing test was weakened to make the suite pass.
+- [ ] Reactive code is tested with `StepVerifier` / `WebTestClient`.
+
+## Delivery
+
+- [ ] PR targets the integration branch: `release/qa` (gateway, agents) or `main` (FE,
+      codescan, litellm, local-agent, forge). Merging `release/qa` / FE `main` deploys QA.
+- [ ] The PR states how it was verified and how to verify it on QA after the merge (curl,
+      log query, bundle grep) and the rollback revision (read live, with traffic
+      percentages).
+- [ ] Conventional commit subject: `type(scope): summary`.

package/.claude/standards/layered-architecture.md

@@ -0,0 +1,163 @@
+# Layered architecture
+
+Decision records, all in `vh-api-gateway/docs/adr/`: ADR-001 (only LiteLLM knows models),
+ADR-002 (package-by-feature with inner layers), ADR-003 (rename to vh-api-gateway,
+`io.visionhammer.*`), ADR-004 (the workspace automation level drives PolicyGate).
+
+## Platform boundaries (v2)
+
+```
+browser -> vision-heart-glow (React SPA)
+             |  /api/v1/*                          -> vh-api-gateway   (BFF, auth, tenants, integrations,
+             |                                                          incidents, notifications, PolicyGate)
+             |  /api/v2/agents/software-engineer/* -> agent2           (debug/fix/implement/PR, CodeScan product)
+             |  /api/v2/*  (everything else)       -> orchestrator     (vh-agents)
+vh-api-gateway --AgentTaskPort/AgentRunPort/AgentReviewPort--> orchestrator / agents
+vh-agents --LlmPort (vh-smart + vh_tier + vh_task)--> vh-litellm --> model providers
+vh-agents --PolicyGateGuard--> gateway /api/v1/internal/policy/evaluate (before every repo write)
+agent2 --Cloud Run Job codescan-scan (europe-west1)--> codescan worker --HMAC callback--> agent2
+Jira --Forge app (glue)--> vh-api-gateway;   client infra <--WS tunnel/MCP--> deepdebug-local-agent
+```
+
+Hard lines:
+- **Only vh-litellm knows model ids, provider URLs and provider keys.** Everyone else asks
+  for a capability: `model: vh-smart` plus `metadata.vh_tier` (`max|reasoning|routine|bulk`)
+  plus `metadata.vh_task`.
+- **The gateway does not call LLMs.** AI work goes to vh-agents through the `agenttask`
+  ports. The gateway keeps the control plane (PolicyGate: tiers, budget, residency, kill
+  switch), expressed without model names.
+- **One source of autonomy (ADR-004).** The workspace automation level decides the
+  PolicyGate mode per action; `tenant_policies.operation_mode` is only a ceiling
+  (`effective = min(ceiling, workspace level)`). Every repo-writing agent tool is gated and
+  sends `diffFiles`. `RUN_SHELL_SAFE` covers proven-safe build/test/lint commands.
+  `DELETE_BRANCH`, `CLOSE_PR` and `SETUP_ENVIRONMENT` always need a human.
+- **No autonomous merge anywhere.** Agents open PRs. Only a human approval in the gateway
+  merges.
+- Services talk over HTTP APIs and ports, never through another service's tables. A table
+  shared on purpose (for example `invites`) is documented in both repos' context.
+
+## Inside a service: features with four layers, plus a shared kernel
+
+```
+io.visionhammer.gateway.
+  <feature>/          admin agenttask cloud governance identity incidents integrations
+    api/              logs notifications onboarding tenancy trigger workspace
+    application/
+    domain/
+    infrastructure/
+  shared/             persistence crypto mail pii localagent idtoken audit
+  config/ filter/ health/ migration/ security/ util/ web/     (kernel: no feature code)
+```
+
+| Layer | Holds | May depend on |
+|---|---|---|
+| `api` | controllers, request/response DTOs, HTTP/SSE mapping, validation | own `application`, `domain`; kernel; other features' `application` |
+| `application` | use cases (one intent per class), orchestration, transactions, guards; ports that carry kernel types | own `domain`; kernel; other features' `application` |
+| `domain` | entities, value objects, pure rules, ports over domain/JDK types | JDK and Reactor `Mono`/`Flux` only |
+| `infrastructure` | R2DBC stores, HTTP clients, Redis, adapters that implement the ports | own `application`, `domain`; kernel; other features' `application` |
+
+Dependencies point inward: `api -> application -> domain`, and `infrastructure` implements
+ports. Concretely:
+
+- **`domain` is framework-free.** No Spring, R2DBC, Reactor Netty, and no kernel class
+  (`shared`, `config`, `security`, ...). No other layer either.
+- **`api` never touches `infrastructure`.** Controllers call use cases, never repositories
+  or clients.
+- **`application` never depends on `api` or `infrastructure`.** A use case knows a port,
+  never the adapter, the SQL or the HTTP.
+- **Cross-feature calls go only through the other feature's `application`.** Never import
+  another feature's `api`, `domain` or `infrastructure`. Need its data? Call its use case or
+  its application port (for example `incidents.application.IncidentReader`).
+- DTOs stay at the edge; entities and rows are never returned as JSON.
+- No LLM provider, router or model type in any layer of the gateway (ADR-001).
+
+### Where ports and adapters go
+
+- **Port = interface**, named for what the use case needs (`*Store`, `*Reader`,
+  `*Writer`, `*Port`, `*Gateway`). **Adapter = the implementation** in
+  `<feature>.infrastructure` (`*R2dbcStore`, `*Client`, `*Adapter`).
+- **Default: the port lives in `domain`**, when its signature uses only domain and JDK
+  (or `Mono`/`Flux`) types.
+- **Port in `application` when it carries a legacy or kernel type.** If a method takes or
+  returns a type the domain may not import (a shared R2DBC row such as `UserEntity`, the
+  Mongo-mapped `IncidentDocument`, a `shared.persistence` entity), the port goes in
+  `application`. Say so in its Javadoc, and say when it moves to `domain` (for example once
+  the Mongo fallback is retired). Examples: `identity.application.UserAccountStore`,
+  `incidents.application.IncidentReader`.
+- A store port for an existing repository mirrors it one for one, so every statement is
+  the one that ran before the port existed.
+- **The shared kernel never depends on a feature.** When kernel code needs something a
+  feature owns, the kernel declares the port and the feature implements it (for example
+  `shared.localagent.CustomerCloudRunIdTokens`, implemented in `logs`).
+
+### The shared kernel
+
+Code that several features use and no single feature owns: `shared.persistence` (rows
+several features read or write), `shared.crypto`, `shared.mail`, `shared.pii`,
+`shared.localagent`, `shared.idtoken`, `shared.audit`, plus the cross-cutting `config`,
+`filter`, `health`, `migration`, `security`, `util` and `web`. Code goes there only when two
+or more features need it and none owns it. It is not a `common/` dumping ground: if one
+feature owns it, it lives in that feature.
+
+The legacy by-type packages (`service`, `controller`, `entity`, `repository`, `model`,
+`client`) are gone, and a test keeps them gone.
+
+## Adding a feature, or moving code into one
+
+Each move is its own PR series, with no behaviour change mixed in:
+
+1. **Characterize first** (`test(...)`: *characterize X before the Y move*). Before moving
+   anything, pin today's behaviour in `*CharacterizationTest` classes: the exact SQL text
+   and binds (a recording `DatabaseClient`), HTTP status and body shapes, webhook
+   signatures, audit rows, ordering on every path. Build the service in exactly one
+   helper ("the only line that knows the constructor"), so the move changes one line per
+   test. The tests must pass on the old layout.
+2. **Ports** (`refactor(...)`: *ports for ...*). Put a `*Store` or `*Port` interface in
+   front of every repository or client the use cases touch, following the placement rule
+   above. Characterization stays green.
+3. **Move** (`refactor(...)`: *move X into X.{api,application,domain,infrastructure}*).
+   This is a mechanical move. Add the feature to `LayeredArchitectureTest.LAYERED_FEATURES`
+   in the same PR (it is never removed afterwards). If repositories moved, update
+   `@EnableR2dbcRepositories` base packages. Characterization still passes, with only
+   imports and the constructor helper changed.
+4. **Clean up.** Keep the sources ASCII-only (`LC_ALL=C grep -n '[^ -~]'` prints nothing).
+   Record in the repo's `.claude/context.md` where things now live.
+5. **Verify by use** after the QA deploy: boot logs, a real call on each moved endpoint.
+   A green suite alone does not prove the wiring.
+
+New code starts directly in a feature. Ask which feature owns it, then put the rule in
+`domain`, the flow in `application`, the HTTP in `api` and the I/O in `infrastructure`.
+
+## Guard tests (gateway, `src/test/java/io/visionhammer/gateway/architecture/`)
+
+| Test | Enforces |
+|---|---|
+| `LayeredArchitectureTest` | each listed feature uses the layout; domain is framework- and kernel-free; api does not reach infrastructure; application does not depend on api or infrastructure; features only talk through `application`; `sharedKernelDependsOnNoFeature`; no class or source file in the retired by-type packages; no LLM provider type in a feature |
+| `LlmAgnosticRatchetTest` | ADR-001 ratchet: provider coupling (bytecode and source text) can only shrink; baselines in `src/test/resources/architecture/` |
+| `R2dbcRepositoryScanCoverageTest` | every R2DBC repository sits under a scanned package and the right scanner (R2DBC vs Mongo) owns it |
+| `BeanConstructorResolvabilityTest` | every bean has one resolvable constructor, so the context still boots |
+| `ComponentScanCoversNewPackagesTest` | the scan root is `io.visionhammer.gateway`; nothing under the old `com.deepdebug` |
+| `NoAutonomousMergeArchitectureTest` | exactly one merge call, reached only from the human approval |
+| `AutomationGateArchTest` | every patch-applying entry point depends on `AutomationGateService` |
+
+vh-agents has its own guards in `shared/src/test/.../governance/`
+(`NoDirectProviderCallsGuardTest`, `NoAutonomousMergeArchitectureTest`, the
+`PolicyGateGuard*Test` family) and `orchestrator/.../automation/AutomationGateArchTest`.
+Its root package is `io.visionhammer.agents.*`. The layered layout is not enforced there
+yet: new packages follow the same four layers, and only `shared/.../llm/` (`LlmPort`,
+`LiteLlmEndpoint`, `LiteLlmChatAdapter`) may reach the LiteLLM proxy.
+
+Never weaken a guard to get a PR green: fix the dependency instead.
+
+## Other stacks, same idea
+
+| Repo | Edge | Application | Domain / core | Adapters |
+|---|---|---|---|---|
+| frontend | `pages/`, route guards | hooks (React Query) | `lib/` pure functions and types | `lib/api/*` (only place that does HTTP) |
+| codescan | `src/main.py` CLI, `src/worker/` | worker pipeline | `src/scoring`, `src/normalization` (pure) | engines (semgrep/gitleaks/trivy), `src/llm/litellm.py`, `src/db` |
+| vh-litellm | `config.yaml` | `vh_plugins/smart_router.py` hook | `vh_plugins/smart_router_policy.py` (no litellm import) | LiteLLM runtime |
+| local-agent | `src/routes`, `server.js` | `src/workspace`, `src/patch` | `src/detectors`, `src/validators` | `src/adapters/*`, `src/git`, tunnel |
+| forge app | `manifest.yml` endpoints | `src/resolvers` | none (glue only) | `vh-gateway` remote |
+
+The same rules apply: the core does not import the edge or the adapters, I/O goes behind
+one adapter module, and pure logic has tests without network or database.

package/.claude/standards/node.md

@@ -0,0 +1,45 @@
+# JavaScript on Node.js
+
+Applies to deepdebug-local-agent: plain JavaScript, ESM (`"type": "module"`), Node 18+
+(CI publishes with Node 20), and the `node:test` runner. It runs **inside customer
+infrastructure**, so every mistake is ours on their machine.
+
+## Style
+
+- ESM `import`/`export` only; no `require`. Use `node:` prefixes for built-ins
+  (`node:fs/promises`, `node:child_process`).
+- `async`/`await`, no callback pyramids. Every promise is awaited or explicitly handled.
+  An unhandled rejection is a bug.
+- Add JSDoc `@param`/`@returns` types on exported functions. Validate inputs at route
+  handlers.
+- New code goes in focused modules under `src/` (`routes/`, `workspace/`, `adapters/`,
+  `git/`, `validators/`). Don't grow `server.js` further. When you touch it, extract.
+- Constants for ports, timeouts and limits; config from `~/.deepdebug/config.json` and env
+  vars.
+- Use a logger with levels, not ad-hoc `console.log` spam, and never log secrets
+  (`DEEPDEBUG_API_KEY`, tokens, git credentials in URLs).
+
+## Security (local-agent specific)
+
+- **Process execution:** `spawn`/`execFile` with an argument array and an explicit `cwd`
+  inside the workspace. Never `exec` with an interpolated string or `shell: true` with any
+  user, gateway or repo input. Validate branch names, refs and file paths against strict
+  patterns first.
+- **Filesystem:** resolve and confine every path to the workspace root (reject `..`,
+  absolute paths and symlink escapes) before reading, writing or patching. Keep backups
+  under the configured backup dir, never `/tmp` on shared mounts.
+- **Network:** the agent talks to the configured gateway (HTTP and WS tunnel) and to local
+  services it was told to watch. No other egress. New listeners (HTTP, MCP) must bind to
+  localhost by default and require the agent token; don't widen existing ones.
+- **Log ingestion:** customer log lines can contain secrets and PII. Redact known token
+  shapes before forwarding, and forward only what the incident needs.
+- **No LLM calls from here.** AI work happens in vh-agents through vh-litellm; the agent is
+  the hands (logs, workspace, git, tunnel), not the brain.
+- **Supply chain:** the npm package is published from `main` (`npm-publish.yml`). Keep
+  dependencies few and pinned; never commit `.tar.gz` bundles, keys or credentials.
+
+## Tests
+
+`npm test` (`node --test`). Adapters are tested against fixtures in `test/fixtures/`;
+process and git calls are tested with fakes at the `child_process` boundary. Every guard
+(path confinement, open gate, capability access) has a test proving the reject path.