feat(acp): implement F102 transparent ACP agent server

[pocky]

Summary

• Implements F102: a transparent ACP (Agent Communication Protocol) server that exposes AWF workflow execution as JSON-RPC 2.0 slash commands over stdio, enabling external agents (Claude Desktop, IDEs) to discover and execute workflows without requiring changes to the workflow definitions
• Adds multi-turn conversation parking support so long-running or interactive workflows can park mid-execution, yield control back to the ACP client, and resume on the next turn — matching how real agent conversations work
• Extends the REST API and pack discovery so workflow packs are advertised as first-class ACP slash commands with slash-safe name encoding, completing the "transparent" contract where existing workflows become ACP-native without modification
• Introduces a fully standalone pkg/acpserver library (JSON-RPC framing, SSE fanout, event projection, input bridging) and a new awf acp-serve CLI command with complete wiring, tests, and architecture validation

Changes

ACP Server Core (pkg/acpserver)

• pkg/acpserver/server.go: New JSON-RPC 2.0 server over stdio with session lifecycle, tool dispatch, and graceful shutdown
• pkg/acpserver/protocol.go: ACP protocol types and JSON-RPC envelope definitions
• pkg/acpserver/types.go: Shared value types for ACP request/response payloads
• pkg/acpserver/doc.go: Package documentation with architecture overview, protocol invariants, and usage patterns
• pkg/acpserver/server_test.go, pkg/acpserver/protocol_test.go, pkg/acpserver/types_test.go: Full unit test coverage
• pkg/acpserver/goroutine_leak_test.go: Goroutine leak detector ensuring server shutdown is clean
• pkg/acpserver/architecture_test.go: Architecture constraint tests (no external dependencies)
• pkg/acpserver/writeframe_internal_test.go: Internal frame-writing path tests

ACP Infrastructure (internal/infrastructure/acp)

• internal/infrastructure/acp/doc.go: Package documentation with adapter patterns and SSE lifecycle
• internal/infrastructure/acp/event_projector.go: Projects domain workflow events onto ACP SSE streams
• internal/infrastructure/acp/fanout_publisher.go: Fan-out SSE publisher delivering events to all connected ACP clients
• internal/infrastructure/acp/input_reader.go: Bridges ACP turn continuations into the workflow UserInputReader port
• internal/infrastructure/acp/message.go: ACP message construction helpers
• internal/infrastructure/acp/renderer.go: ACP-aware display renderer translating domain events to ACP protocol messages
• internal/infrastructure/acp/*_test.go: Full unit test coverage for all adapters (734+ lines for renderer alone)

ACP Application Layer

• internal/application/acp_session.go: ACP session entity managing per-connection lifecycle and run state
• internal/application/acp_session_service.go: Service orchestrating session creation, workflow dispatch, multi-turn parking, and shutdown (954 lines)
• internal/application/acp_errors.go: ACP-specific error types and JSON-RPC error code mapping
• internal/application/acp_session_service_test.go: Comprehensive unit tests for session service (970 lines)
• internal/application/acp_session_service_concurrency_test.go: Concurrency and race-condition tests
• internal/application/acp_session_service_parking_test.go: Multi-turn workflow parking and continuation tests
• internal/application/acp_session_test.go: Session entity tests
• internal/application/acp_audit_fixes_test.go: Audit-driven regression tests for identified quality findings

ACP CLI Command

• internal/interfaces/cli/acp_serve.go: awf acp-serve command implementation with flag parsing, server startup, and signal handling (436 lines)
• internal/interfaces/cli/acp_wiring.go: Dependency wiring for ACP server — assembles all infrastructure adapters and injects into session service
• internal/interfaces/cli/acp_serve_test.go: CLI command unit tests
• internal/interfaces/cli/acp_serve_statestore_test.go: State store integration tests for ACP serve path
• internal/interfaces/cli/acp_wiring_test.go: Wiring correctness tests
• internal/interfaces/cli/root.go: Register acp-serve subcommand
• internal/interfaces/cli/serve.go: Add ACP serve to top-level serve group

Domain Ports & Errors

• internal/domain/ports/acp_client.go: ACPClient port interface (session callbacks, event push, input request)
• internal/domain/ports/acp_client_test.go: Port contract tests
• internal/domain/ports/logger.go: Add ACP-related log level constants
• internal/domain/ports/repository.go: Extend repository interface with pack workflow listing for ACP catalog
• internal/domain/ports/repository_test.go: Repository interface tests
• internal/domain/errors/codes.go: Add ACP error codes (SessionNotFound, WorkflowNotFound, InvalidCommand)
• internal/domain/errors/codes_test.go: Error code tests
• internal/domain/workflow/agent_role.go: Add role fields needed for ACP session context
• internal/domain/workflow/entry.go: Add EntryNames() helper for ACP workflow catalog construction
• internal/domain/workflow/entry_test.go: Entry helper tests

Execution Service & Application Service

• internal/application/execution_service.go: Inject ACP renderer factory; route ACP-mode executions through dedicated display pipeline
• internal/application/execution_service_render_test.go: Renderer injection tests
• internal/application/execution_setup.go: Wire ACP renderer context into execution setup
• internal/application/execution_setup_test.go: Execution setup tests
• internal/application/service.go: Expose ListAllWorkflows for ACP catalog; add pack discovery delegation
• internal/application/service_test.go: Service-layer catalog tests
• internal/application/loop_executor_core_test.go: Update loop executor tests for new execution context shape
• internal/application/plugin_service_interface_test.go: Plugin service interface alignment
• internal/application/role_loader_test.go: Role loader tests (213 new lines)

Pack Discovery for ACP

• internal/infrastructure/workflowpkg/discoverer.go: Expose pack workflows to ACP catalog with slash-safe name encoding
• internal/infrastructure/workflowpkg/discoverer_test.go: Pack discoverer tests (344 lines)
• internal/infrastructure/workflowpkg/manifest.go: Add manifest helpers for ACP name round-trip mapping
• internal/infrastructure/workflowpkg/manifest_test.go: Manifest tests

REST API Integration

• internal/interfaces/api/routing.go: Extract route registration to separate file for cleaner composition
• internal/interfaces/api/routing_test.go: Route registration tests
• internal/interfaces/api/bridge.go: Wire pack workflow execution through REST API bridge
• internal/interfaces/api/bridge_test.go: Bridge tests
• internal/interfaces/api/handlers_executions.go: Handle pack workflow execution requests
• internal/interfaces/api/handlers_executions_test.go: Execution handler tests
• internal/interfaces/api/handlers_workflows.go: List pack workflows via REST API
• internal/interfaces/api/handlers_workflows_test.go: Workflow handler tests
• internal/interfaces/api/doc.go: Updated API package documentation
• internal/interfaces/api/server_test.go, internal/interfaces/api/sse_test.go: Updated server and SSE tests
• internal/interfaces/api/types.go: Add pack workflow response types

Infrastructure: Roles, Skills, Repository, XDG

• internal/infrastructure/roles/doc.go: Package documentation for roles infrastructure
• internal/infrastructure/roles/filesystem_repository.go: Path traversal hardening and XDG roles dir support
• internal/infrastructure/roles/filesystem_repository_test.go: Role repository tests
• internal/infrastructure/skills/filesystem_repository.go: Align with roles repository patterns
• internal/infrastructure/skills/filesystem_repository_test.go: Skills repository tests
• internal/infrastructure/repository/composite_repository.go: Add pack source to composite repository
• internal/infrastructure/repository/composite_repository_test.go: Composite repository tests
• internal/infrastructure/repository/source.go: Remove obsolete source field
• internal/infrastructure/repository/yaml_repository.go: Path traversal validation improvements
• internal/infrastructure/repository/yaml_repository_path_traversal_test.go: Path traversal attack tests
• internal/infrastructure/xdg/xdg.go: Add roles directory resolution
• internal/infrastructure/xdg/xdg_roles_dir_test.go: XDG roles dir tests
• internal/infrastructure/xdg/xdg_test.go: XDG test updates
• internal/infrastructure/agents/base_cli_provider.go: Attach render context for ACP output routing
• internal/infrastructure/agents/base_cli_provider_render_test.go: Render context injection tests

CLI: Pack Resolver, Validate, TUI, Workflow Command

• internal/interfaces/cli/pack_resolver.go: Resolve pack workflow name from ACP slash-safe encoding
• internal/interfaces/cli/pack_resolver_test.go: Pack resolver tests
• internal/interfaces/cli/validate.go: Add ACP command name validation helpers
• internal/interfaces/cli/validate_helpers_test.go: Validate helper tests
• internal/interfaces/cli/validate_role_test.go: Role validation tests
• internal/interfaces/cli/workflow_cmd.go: Wire pack resolver for workflow execution
• internal/interfaces/cli/workflow_cmd_test.go: Workflow command tests
• internal/interfaces/cli/mcp_serve_test.go: MCP serve test alignment
• internal/interfaces/cli/run_pack_wiring_test.go: Pack wiring tests
• internal/interfaces/cli/root_test.go: Root command registration tests
• internal/interfaces/cli/ui/agent_renderer.go: ACP render mode in agent renderer
• internal/interfaces/tui/command.go: Add ACP serve entry to TUI command list
• internal/interfaces/tui/command_test.go: TUI command tests
• internal/interfaces/tui/tab_workflows.go: Display pack workflows in TUI workflows tab
• internal/interfaces/tui/tab_workflows_test.go: TUI workflows tab tests

Shared Packages

• pkg/display/event.go: Add ACP event types
• pkg/display/renderer_context.go: New RendererContext carrying ACP vs CLI render mode
• pkg/display/renderer_context_test.go: Renderer context tests
• pkg/validation/name.go: ACP command name validation and slash-safe encoding/decoding utilities
• pkg/validation/name_test.go: Name validation tests

Tests, Fixtures & Integration

• tests/integration/acp/acp_jsonrpc_e2e_test.go: End-to-end JSON-RPC integration tests over stdio (358 lines)
• tests/integration/acp/acp_goroutine_leak_test.go: Integration-level goroutine leak tests
• tests/integration/acp/testhelpers_test.go: ACP integration test helpers
• tests/integration/api/pack_workflow_test.go: REST API pack workflow integration tests (298 lines)
• tests/integration/api/functional_test.go, tests/integration/api/server_integration_test.go: API integration test updates
• tests/fixtures/acp/valid.json, tests/fixtures/acp/malformed.json: ACP protocol message fixtures
• tests/fixtures/acp/workflows/trivial.yaml, tests/fixtures/acp/workflows/long-running.yaml, tests/fixtures/acp/workflows/input-echo.yaml: ACP test workflow fixtures
• tests/fixtures/api/packs/speckit/manifest.yaml, tests/fixtures/api/packs/speckit/state.json, tests/fixtures/api/packs/speckit/workflows/specify.yaml: REST API pack fixtures
• internal/testutil/env.go: Test environment helpers
• internal/testutil/mocks/mocks.go: Additional mock implementations

Architecture & Configuration

• .go-arch-lint.yml: Register pkg-acpserver and infra-acp components with dependency rules
• .zpm/kb/default/knowledge.pl, .zpm/kb/feedback/knowledge.pl, .zpm/kb/pr_feature_f102_acp_transparent_agent_server/knowledge.pl: ZPM knowledge base entries for F102 decisions and feedback rules
• .zpm/kb/feedback/journal.wal, .zpm/kb/pr_feature_f102_acp_transparent_agent_server/journal.wal: ZPM WAL journals
• .zpm/mounts.json: Mount PR-scoped ZPM segment for F102
• .awf.yaml: Set log level to debug during development
• .gitignore: Ignore .awf/storage/states/ and .awf/storage/logs/
• go.mod: Add new dependencies for ACP server package

Documentation

• docs/ADR/018-acp-transparent-agent-server-protocol.md: Architecture Decision Record for ACP protocol choice and design tradeoffs
• docs/ADR/README.md: Register ADR-018
• docs/user-guide/acp-server.md: Full user guide for awf acp-serve command
• docs/user-guide/api.md: Document pack workflow REST API endpoints
• docs/user-guide/agent-steps.md: Document ACP-specific agent step behavior
• docs/user-guide/workflow-packs.md: Document ACP slash command integration for packs
• docs/user-guide/workflow-syntax.md: Minor syntax clarifications
• docs/reference/error-codes.md: Add ACP error codes
• docs/README.md: Link to new ACP server guide
• docs/superpowers/plans/2026-05-31-acp-full-execution-stack.md: Implementation plan document
• CHANGELOG.md: F102 release notes
• CLAUDE.md: Updated architecture rules from F102 learnings
• README.md: Mention ACP server in feature list

Test plan

• make build passes and awf acp-serve --help shows the command with expected flags
• echo '{"jsonrpc":"2.0","id":1,"method":"session/new","params":{}}' | awf acp-serve returns a valid JSON-RPC session response listing available workflows as slash commands
• make test passes with zero failures and race detector clean (make test-race)
• make lint reports zero violations

Closes #360

---

Generated with awf commit workflow