From 84676e001404d0c2aa6d51ae91c46740c8c71cd9 Mon Sep 17 00:00:00 2001
From: Remylus Losius <remyluslosius@gonaibo.com>
Date: Mon, 15 Jun 2026 06:56:49 -0400
Subject: [PATCH] fix(spec): correct two stale file references found in the
 spec audit

Part 1 of the spec-prose drift cleanup (read-only audit found these):

- evidence/envelope.spec.yaml: the deferred AC-10 note referenced
  `api/envelope.go`, which does not exist. The EvidenceEnvelope struct
  lives in api/transaction.go. Corrected the reference.
- agent/handler-port-filepermissions.spec.yaml: described the
  controller-side handler shim as a deliverable file
  `internal/agent/remotehandler/remotehandler.go` + scope entry. That
  package was never created; the shim was implemented as
  `agentBackedHandler` in internal/engine/engine.go (returned by
  engine.lookupHandler when an AgentClient is set). Corrected both the
  deliverable description and the scope entry to the real location.

Spec-prose-only; no AC ids or test annotations touched, so coverage is
unaffected. specter 119/119.

The remaining audit findings (a stale `internal/deadman/` path and ~26
renamed/missing `Locked by Test...` references across ~12 specs) need
per-spec judgment and are scoped separately.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../handler-port-filepermissions.spec.yaml      | 17 ++++++++++-------
 specs/evidence/envelope.spec.yaml               |  2 +-
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/specs/agent/handler-port-filepermissions.spec.yaml b/specs/agent/handler-port-filepermissions.spec.yaml
index 1f87059..19b34aa 100644
--- a/specs/agent/handler-port-filepermissions.spec.yaml
+++ b/specs/agent/handler-port-filepermissions.spec.yaml
@@ -32,12 +32,15 @@ spec:
                always false (the agent IS the target), Close
                no-op.
 
-            2. `internal/agent/remotehandler/remotehandler.go`
-               — controller-side shim wrapping
-               `*client.Client` + a mechanism name; satisfies
-               `api.Handler`, `api.CaptureHandler`,
-               `api.RollbackHandler` by forwarding to
-               client.Apply/Capture/Rollback. The
+            2. The controller-side shim, implemented as
+               `agentBackedHandler` in
+               `internal/engine/engine.go` (returned by
+               `engine.lookupHandler` when an AgentClient is
+               set, NOT a separate `internal/agent/remotehandler`
+               package) — wraps the engine's `AgentClient` + a
+               mechanism name; satisfies `api.Handler`,
+               `api.CaptureHandler`, `api.RollbackHandler` by
+               forwarding to client.Apply/Capture/Rollback. The
                `transport` argument the engine passes is
                ignored (the agent runs locally on the
                target; it doesn't use a controller-supplied
@@ -119,7 +122,7 @@ spec:
         scope:
             includes:
                 - "internal/agent/transport/local/local.go + _test.go"
-                - "internal/agent/remotehandler/remotehandler.go + _test.go"
+                - "internal/engine/engine.go: agentBackedHandler (the agent-routing handler shim, via lookupHandler) + _test.go"
                 - "internal/agent/server/server.go + _test.go"
                 - "internal/engine/engine.go: WithAgentClient option"
                 - "cmd/kensa/main.go: agent-mode-default (KENSA_NO_AGENT opt-out) path"
diff --git a/specs/evidence/envelope.spec.yaml b/specs/evidence/envelope.spec.yaml
index 4c2688e..0a04d6c 100644
--- a/specs/evidence/envelope.spec.yaml
+++ b/specs/evidence/envelope.spec.yaml
@@ -165,7 +165,7 @@ spec:
     #     not yet written. Future deliverable: schema-codegen +
     #     round-trip test.
     #   - AC-10 (cross-repo schema match between kensa-spec/yaml
-    #     and api/envelope.go Go struct):
+    #     and the api.EvidenceEnvelope Go struct in api/transaction.go):
     #     Requires a cross-repo schema comparison step
     #     (`go generate` or CI check). Tracked in
     #     SPECTER_FEATURE_REQUEST.md.