Files

fs 5f156661fd docs: fix guard count drift in CLAUDE.md, README, and workflow

Update security guard references from 9 to 10 (GR-SEC-010 was missing),
code reviewer guards from 13 to 17 (new GR-CORE-LAYERS, GR-CORE-MODULE,
GR-CORE-META, GR-UI-TAXONOMY), and total guard count from 22 to 27.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-13 20:50:24 +02:00

5.4 KiB

Raw Blame History

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 (27 guards): .agents/checks/guard-catalog.json
Quality gates (9 gates): .agents/checks/quality-gates.json
Enforcement policy (workflow trigger + gate enforcement): .agents/checks/enforcement-policy.json
Guard enforcement map (guard -> automated/hybrid/reviewer evidence): .agents/checks/guard-enforcement-map.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 (17 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.

Workflow Trigger Policy

Workflow triggering is risk-based and centrally defined in:

.agents/checks/enforcement-policy.json (full_workflow_required_when)
.agents/checks/enforcement-policy.json (quick_fix_allowlist)

Interpretation:

Full workflow is mandatory for risk/security/data-boundary/module/cross-layer changes
Quick fixes are only exempt if they match the explicit allowlist
>1 layer remains a useful heuristic but is no longer the sole trigger

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 (17 guards): GR-CORE-003, GR-CORE-007, GR-CORE-010, GR-CORE-011, GR-CORE-012, GR-CORE-LAYERS, GR-CORE-MODULE, GR-CORE-META, GR-TEST-001, GR-TEST-002, GR-UI-014, GR-UI-LIST, GR-UI-DETAIL, GR-UI-A11Y, GR-UI-I18N, GR-UI-REUSE, GR-UI-TAXONOMY

Security Reviewer (10 guards): GR-SEC-001 through GR-SEC-010

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)
Guard reference integrity (GR-*/QG-*) across docs/agents/tests/bin
Guard enforcement mapping completeness and automated evidence file existence

5.4 KiB Raw Blame History