breadcrumb-the-shire/.agents/workflow.md

# 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