refactor: relocate agent-system/ to .agents/ with 7-role workflow restructure

Moves the agent workflow system from agent-system/ to .agents/ (dotfile convention). Restructured from 5-role to 7-role pipeline: adds Analyst and splits Reviewer into Code Reviewer + Security Reviewer. Removes all old workflow run artifacts. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 18:23:04 +01:00
parent ef72b34c40
commit 4dd6d451f6
136 changed files with 1357 additions and 7890 deletions
--- a/.agents/workflow.md
+++ b/.agents/workflow.md
@@ -0,0 +1,125 @@
+# Agent Workflow
+
+Last updated: 2026-03-19
+
+## Overview
+
+This project uses a 7-role workflow for issue and feature delivery.
+
+```
+Analyst → Planner → Executor → Code Reviewer ──┐
+                                                ├→ Finalizer
+                        Security Reviewer ──────┤
+                        Acceptance Tester ───────┘
+```
+
+Primary goals:
+- Front-load context gathering (Analyst) so downstream roles start informed
+- Separate code quality review from security review for focused attention
+- Explicit guard IDs (`GR-*`), gate IDs (`QG-*`), and success criteria (`SC-*`) across all roles
+- Fast retry loop from reviewers back to executor
+
+Source of truth:
+- Guard catalog (22 guards): `.agents/checks/guard-catalog.json`
+- Quality gates (9 gates): `.agents/checks/quality-gates.json`
+- Contracts: `.agents/contracts/`
+
+---
+
+## Roles
+
+### Analyst
+- **Input:** issue description or feature request
+- **Output:** `analysis.json` (see `.agents/contracts/analyst.schema.json`)
+- Gathers context: affected layers, files, patterns, tests, security surface
+- Does NOT propose solutions — only structures facts for the Planner
+
+### Planner
+- **Input:** `analysis.json`
+- **Output:** `plan.json` (see `.agents/contracts/planner.schema.json`)
+- Defines scope, guard selection, success criteria, implementation steps, risks
+- References concrete file paths from analysis — does not re-explore codebase
+
+### Executor
+- **Input:** approved `plan.json`
+- **Output:** `execution-report.json` (see `.agents/contracts/executor.schema.json`)
+- Implements plan, runs quality gates, provides guard evidence
+
+### Code Reviewer
+- **Input:** code diff + `execution-report.json`
+- **Output:** `review-code.json` (see `.agents/contracts/reviewer-code.schema.json`)
+- Scope: architecture, conventions, testing, UI standards (13 guards)
+- Guards: `GR-CORE-*`, `GR-TEST-*`, `GR-UI-*`
+
+### Security Reviewer
+- **Input:** code diff + `execution-report.json`
+- **Output:** `review-security.json` (see `.agents/contracts/reviewer-security.schema.json`)
+- Scope: authz, tenant scope, CSRF, input validation, crypto, file storage (9 guards)
+- Guards: `GR-SEC-*`
+- Any `critical` or `high` finding forces `fail` verdict
+
+### Acceptance Tester
+- **Input:** code diff + `plan.json`
+- **Output:** `review-acceptance.json` (see `.agents/contracts/reviewer-acceptance.schema.json`)
+- Verifies each `SC-*` success criterion is met
+
+### Finalizer
+- **Input:** `review-code.json` + `review-security.json` + `review-acceptance.json`
+- **Output:** `finalize.json` (see `.agents/contracts/finalizer.schema.json`)
+- All three reviews must pass. CI must be green. Otherwise: hold.
+
+---
+
+## State Machine
+
+```
+analyzed → planned → executing → reviewing → finalize → done
+                        ↑            |
+                        └────────────┘  (on any FAIL)
+```
+
+The reviewing state runs Code Reviewer, Security Reviewer, and Acceptance Tester.
+If any reviewer returns `FAIL`, state goes back to `executing` with explicit findings.
+
+## Handover Artifacts
+
+| Role | Artifact |
+|---|---|
+| Analyst | `analysis.json` |
+| Planner | `plan.json` |
+| Executor | `execution-report.json` |
+| Code Reviewer | `review-code.json` |
+| Security Reviewer | `review-security.json` |
+| Acceptance Tester | `review-acceptance.json` |
+| Finalizer | `finalize.json` |
+
+## Fail Loop Rule
+
+No free-text "please improve". Every fail must include:
+- `id`
+- `severity`
+- `file`
+- expected fix
+
+## Guard Assignment
+
+Guards are split by reviewer role (see `reviewer` field in guard-catalog.json):
+
+**Code Reviewer** (13 guards): GR-CORE-003, GR-CORE-007, GR-CORE-010, GR-CORE-011, GR-CORE-012, GR-TEST-001, GR-TEST-002, GR-UI-014, GR-UI-LIST, GR-UI-DETAIL, GR-UI-A11Y, GR-UI-I18N, GR-UI-REUSE
+
+**Security Reviewer** (9 guards): GR-SEC-001 through GR-SEC-009
+
+## What automated tests already enforce
+
+The following concerns are covered by QG-001/QG-003/QG-004 and do NOT need manual guard review:
+- Layering boundaries (CoreStarterkitContractTest)
+- No direct service instantiation in pages (structural rg checks)
+- No superglobals in pages (architecture tests)
+- PSR-4 namespace alignment (autoloader + QG-003)
+- PHP code style (QG-006)
+- Module namespace isolation (ModuleStructureContractTest)
+- Module UI via slots only (NoBookmarksHardcodingTest, NoAddressBookHardcodingTest)
+- Runtime fingerprint (web/index.php fail-fast)
+- Repository sanitizeLimitOffset (RepositoryInterfaceContractTest)
+- List init standard, legacy filter toggle, template RBAC (architecture tests)
+- Component lifecycle contract (architecture tests)