feat(roles): implement F100 dedicated roles/ namespace for agent role discovery

[pocky]

Summary

• Introduces a dedicated roles/ namespace for agent role discovery, replacing the old agents/ directories — roles now live under .awf/roles/, .agents/roles/, $XDG_CONFIG_HOME/awf/roles/, and ~/.agents/roles/ instead of the flat .awf/agents/ and .agents/ paths from F098
• Renames the environment override variable from AWF_AGENTS_PATH to AWF_ROLES_PATH, making the roles and skills namespaces structurally symmetric and preventing ambiguous cross-namespace discovery collisions
• Adds RawSizeBytes to AgentRole so the CLI validator avoids a second os.Stat call, and promotes the 500KB threshold to a named constant (AgentRoleSizeWarnBytes) shared between the infrastructure loader and the validator
• Initialises the ZPM knowledge base (default and feedback memory segments) with the project's constitution rules, architecture integrity checks, and queryable feedback schema, wiring them as auto-mounted project segments

Changes

Domain

• internal/domain/workflow/agent_role.go: Add AgentRoleSizeWarnBytes constant, RawSizeBytes field on AgentRole, and IsPathRef flag on AgentRoleNotFoundError for cleaner error disambiguation in the validator

Infrastructure — Roles

• internal/infrastructure/roles/filesystem_repository.go: Switch from AWF_AGENTS_PATH/.awf/agents/.agents to AWF_ROLES_PATH/.awf/roles/.agents/roles; set IsPathRef: true in LoadFromPath; use AgentRoleSizeWarnBytes constant; populate RawSizeBytes; add crossClientGlobalRolesDir()
• internal/infrastructure/roles/filesystem_repository_test.go: Update all fixture paths to roles/ namespace; add TestLoad_AWFRolesPathOverride (including negative case asserting AWF_AGENTS_PATH is ignored), TestLoad_OldAgentsPathNotFound, TestLoad_SkillsRoleNoCollision; replace manual os.Chdir / defer os.Chdir with testutil.ChdirIsolated
• internal/infrastructure/roles/doc.go: New file — package-level architecture overview for the roles adapter

Infrastructure — Skills

• internal/infrastructure/skills/filesystem_repository.go: Extract skillSizeWarnBytes constant (intentionally decoupled from roles); filter empty candidates before appending paths; fix crossClientGlobalSkillsDir/claudeGlobalSkillsDir to return "" on UserHomeDir error; align path-traversal guard to use ContainsAny("/\\")
• internal/infrastructure/skills/filesystem_repository_test.go: Add TestLoad_NameValidation covering backslash rejection; use fmt.Appendf in two existing tests

Infrastructure — XDG

• internal/infrastructure/xdg/xdg.go: Rename AWFAgentsDir→AWFRolesDir, LocalAgentsDir→LocalRolesDir; guard ConfigHome/DataHome against UserHomeDir errors returning "" instead of "/.config"; expose roles_dir key in AWFPaths()
• internal/infrastructure/xdg/xdg_roles_dir_test.go: New file — tests for AWFRolesDir (XDG priority chain, AWF_CONFIG_HOME override) and LocalRolesDir (structural parity with LocalSkillsDir)
• internal/infrastructure/xdg/xdg_test.go: Assert roles_dir key in AWFPaths tests

Application

• internal/application/role_loader_test.go: Add 11 new tests covering ResolveAgentRole path-vs-name semantics (FR-008/FR-009), BuildRoleSystemPrompt composition, template resolution, nil-repo, nil-role fallback, and error propagation paths

CLI Interface

• internal/interfaces/cli/validate.go: Promote agentRoleCombinedPromptWarnBytes to named constant; pass ctx into validateRoleRefs instead of creating a new context.Background() inside; extract roleContentWarnings helper; replace roleDirExistsWithoutAgentsMD heuristic with IsPathRef flag; emit user-oriented role-not-found messages without exposing internal search paths
• internal/interfaces/cli/validate_role_test.go: Update all fixtures to roles/ namespace; add testutil.ChdirIsolated calls; add assertions verifying that agents/ paths do not appear in error messages; pass context.Background() explicitly
• internal/interfaces/cli/validate_helpers_test.go: New file — unit tests for the extracted roleContentWarnings helper

Test Utilities

• internal/testutil/env.go: New file — ChdirIsolated(t, dir) helper that changes to a directory and restores the original working directory via t.Cleanup, eliminating the manual defer os.Chdir(origDir) pattern repeated across ~12 test functions

ZPM Knowledge Base

• .zpm/kb/default/knowledge.pl: New file — base schema (task graph, component graph, ADR, feedback, integrity violations) and Go constitution rules (hexagonal layer checks, panic detection, coverage thresholds)
• .zpm/kb/feedback/knowledge.pl: New file — queryable feedback segment schema (rule/5, trigger/3, applicable/2, helper aggregations)
• .zpm/kb/feedback/journal.wal: New file — empty WAL for feedback segment
• .zpm/mounts.json: Register feedback segment as auto-mounted alongside default

Documentation & Config

• CHANGELOG.md: Add F100 breaking-changes section with migration guide for all renamed paths and the env variable rename
• CLAUDE.md: Add ZPM project memory usage guide (segment table, read/write query examples, category index)
• README.md: Update Agent Roles bullet to describe the roles/ namespace and AWF_ROLES_PATH
• docs/reference/error-codes.md: Update USER.INPUT.MISSING_ROLE resolution steps to use roles/ paths and AWF_ROLES_PATH
• docs/user-guide/agent-steps.md: Update directory structure examples, search-path table (4 entries, renamed env var), add Role Resolution by-name vs explicit-path guidance table
• docs/user-guide/workflow-syntax.md: Update role: field description path example
• .gitignore: Add .awf/storage/states/ and .awf/storage/logs/

Test Cleanup

• internal/application/loop_executor_core_test.go: Replace named-but-unused parameters with _ in StepExecutorFunc literals to satisfy linter
• internal/application/plugin_service_interface_test.go: Strengthen composite interface assertion to exercise delegated methods at runtime rather than compile-time only

Test plan

• make build && make lint && make test pass with zero violations
• AWF_ROLES_PATH=/tmp/custom-roles awf run <workflow-with-role> resolves roles exclusively from the override path; roles under .awf/roles/ are not consulted
• Moving a role from .awf/agents/go-senior/ → .awf/roles/go-senior/ and running awf validate <workflow> reports valid; leaving it at the old path produces ErrRoleNotFound
• awf validate error message for a missing role contains the role name but does not expose internal filesystem search paths (e.g. no .awf/roles/missing-role in output)

Closes #356

---

Generated with awf commit workflow