--- document: agents.md project: Canonic Associates Ltd Corporate Website + CMS document_type: Team and AI Agent Operating Manual version: 1.0 status: implementation-ready last_updated: 2026-09-02 authority: primary_design_spec: design.md precedence: - approved_change_request - design.md - agents.md - issue_description - code_comments workflow: source_control: git default_branch: main change_method: pull_request requirement_reference_required: true ai_direct_production_access: false --- # Canonic Associates Ltd — Engineering Team & AI Agent Operating Manual ## 0. Purpose This document defines how human contributors and AI development agents execute the solution described in `design.md`. It establishes: - roles and ownership - task boundaries - repository permissions - implementation workflows - review and approval processes - CMS content publishing governance - issue tracking - requirement traceability - documentation maintenance - quality gates - milestone success metrics - AI-specific coding/debugging/documentation instructions No role, including an AI agent, may override `design.md` without an approved change process. --- # 1. Operating principles ## 1.1 Single source of truth `design.md` is the implementation source of truth. Every engineering issue and pull request must reference one or more requirement IDs, for example: ```text REQ-003 SSR public content REQ-007 Full CMS editability REQ-013 Project confidentiality approval ``` ## 1.2 No silent scope changes When implementation reveals a missing requirement: 1. Open a requirement-change issue. 2. State observed gap. 3. State impact. 4. Propose exact change. 5. Identify affected requirement IDs and sections. 6. Obtain approval. 7. Update `design.md`. 8. Update tests/acceptance matrix. 9. Only then merge code depending on the new requirement unless the change is a non-functional defect correction. ## 1.3 Source fidelity Contributors must preserve submitted corporate facts and requirement terminology. If source materials conflict, the contradiction stays visible until an authorized stakeholder resolves it. Example: corporate chronology conflict is tracked as `OI-001`. ## 1.4 Security by default - Least privilege. - No production secrets in source control. - No AI agent direct production credentials. - No unreviewed migration or destructive action. - No private applicant/project documents copied into tickets/prompts. - No bypass of policies for convenience. ## 1.5 CMS first If business-facing content can reasonably change, it belongs in CMS/configuration rather than React/PHP templates. Before writing literal company-facing copy into a component, ask: > "Should a content manager be able to change this without a deployment?" If yes, implement it as CMS data. --- # 2. Team topology ```mermaid flowchart TB PO[Project Sponsor / Product Owner] PM[Project Manager / Delivery Lead] ARCH[Solution Architect / Tech Lead] FE[Frontend Engineers] BE[Backend Engineers] CMS[CMS Developers] DEVOPS[DevOps / Platform] QA[QA Analysts] SEC[Security Reviewer] CONTENT[Content Managers] AIC[AI Code Generation Agent] AID[AI Debugging Agent] AIDO[AI Documentation Agent] AIR[AI Review/Test Agent] PO --> PM PM --> ARCH ARCH --> FE ARCH --> BE ARCH --> CMS ARCH --> DEVOPS PM --> QA PM --> CONTENT ARCH --> SEC FE <--> AIC BE <--> AIC CMS <--> AIC QA <--> AIR FE <--> AID BE <--> AID CMS <--> AID ARCH <--> AIDO ``` --- # 3. Human role definitions # 3.1 Project Sponsor / Product Owner ## Responsibilities - Own business outcomes. - Resolve requirement conflicts. - Approve material scope changes. - Approve final launch. - Ensure required corporate content/assets are supplied. ## Required decisions - `OI-001` corporate history chronology - approved portfolio content - confidential/public project boundaries - legal text approval - brand approval - integration priority decisions ## Success metrics - requirement decisions delivered within agreed SLA - no critical unresolved launch blockers - formal UAT sign-off --- # 3.2 Project Manager / Delivery Lead ## Responsibilities - Maintain roadmap aligned to `design.md` §28. - Create milestone plan. - Manage dependencies from `design.md` §29. - Coordinate daily sync and weekly stakeholder review. - Maintain risk/issue/change logs. - Track requirement coverage. - Coordinate UAT and handover. ## Key artifacts - milestone board - RAID log - change-request register - UAT register - release checklist ## Success metrics - ≥90% sprint commitment predictability after sprint 2 - no unowned blocker older than one business day - 100% merged PRs linked to requirements - milestone exit criteria documented --- # 3.3 Solution Architect / Technical Lead ## Responsibilities - Own architecture consistency. - Enforce Laravel/React/Inertia boundaries. - Approve data model changes. - Review high-risk PRs. - Maintain ADRs. - Resolve cross-team technical dependencies. - Prevent unnecessary distributed complexity. - Ensure customization/plugin boundaries remain stable. ## Mandatory review areas - authentication - authorization - migrations - publishing workflow - integration architecture - public SSR strategy - plugin/module contracts - caching strategy - deployment topology ## Success metrics - zero known critical architecture violations at release - all high-risk changes reviewed - no SSR hydration errors - no duplicated domain rules between frontend and backend - ADRs current for major decisions --- # 3.4 Frontend Engineer ## Primary scope `design.md` §§6–8, 16–17, 23–24. ## Responsibilities - Build React + TypeScript UI. - Implement public SSR-compatible pages. - Implement CSR interactions. - Build design-system components. - Implement content block renderer. - Build responsive layouts. - Implement WCAG behavior. - Ensure no business content is hardcoded. - Optimize bundle, images and hydration. - Write component/E2E support tests. ## Explicit task assignments by roadmap ### Phase 0 - React/Inertia/Vite bootstrap. - SSR client/server entry. - TypeScript configuration. - frontend linting/testing baseline. ### Phase 1 - design tokens - layout primitives - header/footer - navigation - CMS admin shell - initial block renderer - visual page-builder frontend ### Phase 2 - Services, Sectors, Team, News, Downloads templates - SEO components - responsive content variants ### Phase 3 - project list - filters - project detail - gallery - confidentiality-safe display behavior ### Phase 4 - contact forms - RFP form - appointment UX - upload UX - success/error states ### Phase 5 - careers/tenders frontend flows ### Phase 6 - performance work - analytics route events - responsive image integration ### Phase 7 - accessibility fixes - browser fixes - hydration fixes ## Definition of done - component uses tokens - keyboard accessible - responsive - typed - SSR-safe - CMS data driven - tests pass - no console errors - meets route performance budget ## Success metrics - Lighthouse frontend gates met - zero launch-blocking accessibility issues - zero hydration errors - no business-facing hardcoded copy discovered during CMS audit - Playwright public flows pass on Chromium/Firefox/WebKit --- # 3.5 Backend Engineer ## Primary scope `design.md` §§9–14, 18–22. ## Responsibilities - Laravel domain modules. - database schema/migrations. - validation. - policies. - APIs. - jobs/queues. - form workflows. - notifications. - secure file access. - audit logging. - integration adapters. - caching. - backend tests. ## Roadmap assignments ### Phase 0 - Laravel bootstrap - environment/config - DB baseline - authentication - queue/cache/session baseline ### Phase 1 - pages - menus - settings - users/roles - workflow engine - revisions - activity log ### Phase 2 - services - sectors - team - posts - downloads ### Phase 3 - projects - taxonomies - project filters - publication/confidentiality rules ### Phase 4 - enquiries - RFP - appointments - routing - notifications - anti-abuse backend - CRM-ready lead events ### Phase 5 - careers/applications - tenders - protected attachments ### Phase 6 - analytics integration support - Microsoft 365 adapter if approved - ERP/CRM adapter - performance/caching ### Phase 7 - security hardening - query/performance fixes - failure-mode testing ## Success metrics - backend suite green - authorization coverage for every admin write - no unprotected private documents - queue retries and failure visibility implemented - p95 server response time within project budget on representative cached/uncached routes --- # 3.6 CMS Developer This may be a specialization of frontend/backend engineers, but it has explicit ownership because full CMS editability is a core acceptance criterion. ## Primary scope `design.md` §11 and §15. ## Responsibilities - CMS information architecture. - visual block editor. - media library. - menu editor. - settings editor. - publishing workflow UI. - revision history. - preview. - theme controls. - feature flags. - multilingual readiness. - admin dashboards. - configurable notification templates. - webhook configuration. ## Mandatory principle No editor should need source-code access to: - update page copy - replace images - reorder approved page sections - edit navigation - create a service/project/news item - update contact information - update SEO - change approved theme tokens - enable/disable supported optional modules ## Success metrics - 100% business-facing frontend content editable - content managers complete agreed UAT without developer intervention - workflow permissions correctly enforce role boundaries - revision restore succeeds - media usage/deletion protections function --- # 3.7 DevOps / Platform Specialist ## Primary scope `design.md` §§18, 25–27. ## Responsibilities - environment provisioning - CI/CD - Nginx/PHP-FPM - SSR process supervision - queue-worker supervision - Redis - database - object storage - CDN/WAF - SSL - secrets - backups - monitoring - rollback - staging/production parity ## Phase assignments ### Phase 0 - repository protections - CI - dev/staging conventions ### Phase 1–5 - preview/staging deployment - secrets/environment management ### Phase 6 - CDN - caching - RUM/performance monitoring - integration secrets ### Phase 7 - restore drill - load testing support - security configuration validation ### Phase 8 - production release - post-deploy monitoring - rollback readiness ## Success metrics - 99.9% availability architecture configured - daily backups successful - weekly offsite backups verified - restore drill meets ≤4-hour critical recovery target - deployment is repeatable/automated - no plaintext production secrets in repository - rollback proven before launch --- # 3.8 QA Analyst ## Primary scope `design.md` §§23–24 and acceptance requirements. ## Responsibilities - requirements-based test plan - functional testing - E2E automation - browser/device testing - accessibility testing - negative authorization tests - regression - UAT coordination - release sign-off evidence ## Test categories - SSR - hydration - CMS editability - RBAC - publishing workflow - project confidentiality - forms - private uploads - email queues - project filters - SEO - accessibility - performance - browser compatibility ## Success metrics - 100% critical requirements have tests or documented manual verification - zero open P0/P1 defects at launch - no core-flow failures in required browsers - no known hydration errors - CMS hardcoding audit passes --- # 3.9 Security Reviewer ## Responsibilities - review threat model - auth/session/MFA review - authorization coverage - upload security - CSP/security headers - secrets handling - webhooks - rate limiting - dependency risk - penetration/security testing coordination ## Success metrics - zero known critical/high security findings at release, unless formally risk-accepted - all privileged actions authorization-tested - protected data storage/access verified --- # 3.10 Content Manager ## Primary scope Populate and maintain CMS; does not change code. ## Responsibilities - page copy - projects - project media - services - sectors - team - news - careers - tenders - downloads - alt text - SEO metadata - navigation - approved theme/configuration settings ## Source governance Content managers must not "correct" corporate facts independently. Disputed facts must be escalated. ## Publishing workflow ```text Content Administrator / Department -> Department Review -> GGMP Approval -> Chairman approval when required -> Publish ``` ## Success metrics - required launch content complete - images have meaningful alt text - no unapproved/confidential project information published - SEO fields completed for launch pages - stale draft queue monitored --- # 4. AI development agent policy ## 4.1 General AI rules AI agents may assist with: - code generation - test generation - refactoring - debugging - static analysis - documentation - requirement traceability - migration drafting - performance diagnosis - accessibility issue detection AI agents may **not**: - deploy directly to production - access production secrets - merge their own changes - change requirements without approval - approve their own security-sensitive code - invent corporate facts - publish CMS content - expose private CV/project files into prompts/logs - bypass tests to achieve a green build ## 4.2 Required task envelope Every AI task should have: ```yaml task: id: DEV-000 requirement_ids: - REQ-... design_sections: - "design.md §..." objective: "..." allowed_paths: - "app/..." - "resources/js/..." forbidden_paths: - ".env" - "production secrets" acceptance: - "..." tests_required: - "..." output: - "code" - "tests" - "documentation update" ``` The agent should stop and request escalation when the requested change contradicts `design.md`. --- # 5. AI Code Generation Agent ## Purpose Generate implementation code for well-scoped requirements. ## Inputs - issue/task - requirement IDs - relevant `design.md` sections - existing repository code - coding conventions - test expectations ## Workflow 1. Read requirement and design sections. 2. Inspect relevant existing code. 3. State impacted modules internally/in task notes. 4. Implement the smallest coherent change. 5. Add/update tests. 6. Run formatter/linter/tests. 7. Check authorization and CMS-editability. 8. Update technical docs if interfaces changed. 9. Prepare PR description with traceability. ## Coding constraints - Follow established Laravel conventions. - Prefer Form Requests/DTOs for non-trivial validation. - Put authorization in policies/gates/actions, not only UI. - Keep domain rules on server. - React must remain SSR-safe. - Never hardcode mutable company content. - Never create a new dependency without justification. - Never introduce raw SQL where Eloquent/query builder is adequate unless performance evidence justifies it. - Never expose private storage URLs directly. ## Success metric Generated PR passes all automated gates and requires no architectural rewrite during review. --- # 6. AI Debugging Agent ## Purpose Diagnose defects without changing unrelated behavior. ## Required debugging method 1. Reproduce. 2. Capture expected vs actual. 3. Identify requirement IDs. 4. Inspect logs/tests/stack trace. 5. Find minimal root cause. 6. Add failing regression test first where practical. 7. Implement fix. 8. Run targeted test. 9. Run affected suite. 10. Check for security/performance regressions. 11. Document root cause in PR. ## Forbidden behavior - blanket exception suppression - disabling hydration warnings - weakening authorization - disabling tests - removing validation to make a flow pass - broad cache clearing as the only "fix" - modifying production data manually without approved runbook ## Success metrics - regression test added - root cause documented - no unrelated diff - defect does not recur in CI --- # 7. AI Documentation Agent ## Purpose Keep project documentation synchronized with implementation. ## Owned artifacts - `design.md` - `agents.md` - README - ADRs - API docs/OpenAPI - deployment runbook - content model docs - release notes ## Rules - Do not modify source-derived facts without approved change. - Distinguish implementation fact from recommendation. - Preserve requirement IDs. - Update cross-references when sections move. - Ensure examples do not contain real secrets. - Mark deprecated behavior explicitly. - Keep machine-readable frontmatter valid. ## Success metrics - zero undocumented public/API behavior changes - docs pass link/reference checks - requirement traceability remains complete --- # 8. AI Review/Test Agent ## Purpose Review changes independently from the code generator. ## Review checklist - requirement coverage - security - authorization - validation - data migrations - SSR safety - hydration risk - hardcoded business content - accessibility - performance - tests - error states - observability - backward compatibility - documentation ## Severity model - `P0`: production security/data loss/system unavailable - `P1`: core requirement broken - `P2`: significant defect with workaround - `P3`: minor defect/polish - `P4`: suggestion AI review is advisory; human reviewer owns merge approval. --- # 9. Repository access control ## 9.1 Human access | Role | Read | Feature branch write | PR approve | Main direct push | Production deploy | |---|---:|---:|---:|---:|---:| | Product Owner | Yes | No | Business approval | No | No | | Tech Lead | Yes | Yes | Yes | No | With DevOps approval | | Frontend Engineer | Yes | Yes | Scoped | No | No | | Backend Engineer | Yes | Yes | Scoped | No | No | | CMS Developer | Yes | Yes | Scoped | No | No | | DevOps | Yes | Yes | Infra | No | Yes | | QA | Yes | Test paths | QA sign-off | No | No | | Security Reviewer | Yes | Security fixes | Security approval | No | No | | Content Manager | CMS only by default | No | No | No | No | ## 9.2 AI access AI agents: - repository read access: task-scoped - branch write access: sandbox/feature branch only - main branch: no direct write - secrets: denied - production shell: denied - production database: denied - CMS publish permission: denied - merge approval: denied --- # 10. Branching and version control ## 10.1 Branch names ```text feat/REQ-003-ssr-project-pages fix/REQ-013-confidential-project-leak chore/ci-playwright-webkit docs/REQ-033-theme-system ``` ## 10.2 Commit format Recommended Conventional Commits: ```text feat(projects): add CMS-managed project filters fix(auth): enforce publish permission server-side test(ssr): fail on hydration warnings docs(cms): document block schema versioning ``` ## 10.3 Protected branches `main`: - no force push - no direct push - required status checks - required PR - required reviewer - CODEOWNERS for sensitive paths - up-to-date branch before merge where feasible --- # 11. CODEOWNERS / review ownership Recommended: ```text /app/Domain/Identity/ @backend-lead @security /app/Policies/ @backend-lead @security /database/migrations/ @backend-lead @tech-lead /resources/js/Components/ @frontend-lead /resources/js/Pages/Admin/ @cms-lead @frontend-lead /resources/js/SSR* @frontend-lead @tech-lead /.github/workflows/ @devops @tech-lead /config/ @backend-lead @devops /docs/ @tech-lead @documentation /design.md @tech-lead @project-manager /agents.md @tech-lead @project-manager ``` --- # 12. Pull request workflow ## 12.1 Required PR template ```markdown ## Requirement - REQ-... ## Design references - design.md §... ## What changed ## Why ## Security impact ## CMS/content impact ## Data/migration impact ## Tests - [ ] Backend - [ ] Frontend - [ ] E2E - [ ] Accessibility - [ ] Manual ## Screenshots / evidence ## Rollback considerations ## Documentation - [ ] Updated - [ ] Not required ``` ## 12.2 Review levels ### Standard One qualified reviewer. ### High risk Two reviewers including Tech Lead or Security/DevOps owner: - auth/RBAC - migrations with data transformation - private file access - webhooks - payments if later introduced - deployment pipeline - cache invalidation affecting publication - ERP/CRM credential handling ## 12.3 Merge gate No merge when: - CI failed - unresolved P0/P1 review issue - requirement not referenced - migration lacks rollback/forward plan - new business content is hardcoded - authorization is UI-only - production secret appears in diff --- # 13. Daily collaboration protocol ## 13.1 Daily engineering sync Maximum 15 minutes: 1. Completed since last sync. 2. Planned today. 3. Blockers. 4. Requirement/design uncertainty. 5. Cross-team dependency. 6. Upcoming review/deployment risk. Blockers requiring product/management input are logged immediately; do not wait for the next daily sync. ## 13.2 Async update template ```text Done: - ... Next: - ... Blocked: - ... Requirements touched: - REQ-... Needs review from: - ... ``` --- # 14. Issue tracking workflow Statuses: ```text Backlog -> Ready -> In Progress -> In Review -> QA -> UAT (when required) -> Ready for Release -> Done ``` Defects may move: ```text QA/UAT -> Reopened -> In Progress ``` ## 14.1 Issue minimum fields ```yaml issue: id: DEV-... type: feature|bug|chore|docs|security requirement_ids: [] milestone: phase-... owner: ... priority: P0|P1|P2|P3|P4 acceptance_criteria: [] dependencies: [] design_references: [] ``` --- # 15. CMS content deployment workflow Content publication is separate from code deployment. ## 15.1 Approval chain Default: 1. Content Administrator / Department creator 2. Department Review 3. GGMP Approval 4. Chairman approval when required 5. Publish ## 15.2 Project-specific rule No project may publish unless: - approved media is attached - confidentiality classification is complete - `publication_approved=true` - required approver has approved - restricted facts are suppressed appropriately ## 15.3 Content rollback - Unpublish permission required. - Previous revision remains recoverable. - Public cache invalidated on publish/unpublish. - Rollback is audit logged. --- # 16. Knowledge management ## 16.1 Central documentation Repository: ```text /design.md /agents.md /README.md /docs/ adr/ api/ deployment/ content/ qa/ releases/ ``` ## 16.2 ADR format Use Architecture Decision Records for choices that materially affect the system. ```markdown # ADR-00X: Title Status: Proposed | Accepted | Superseded Date: Decision owners: ## Context ## Decision ## Alternatives ## Consequences ## Requirements affected ``` Required ADR candidates: - modular monolith + Inertia SSR - PostgreSQL vs MySQL final production choice - media storage provider - CAPTCHA provider - ERP/CRM integration adapter - multilingual routing strategy - plugin/module mechanism ## 16.3 Requirement updates Every requirement change must update: 1. `design.md` 2. impacted issue acceptance criteria 3. tests 4. architecture/API docs if needed 5. release notes if user-visible Do not maintain a shadow requirements document. --- # 17. Coding standards ## 17.1 PHP/Laravel - PSR-12 / Laravel Pint - strict types where project convention supports it - small controllers - Form Requests - policies - service/action classes for multi-step business logic - typed return values where practical - transactions for multi-record critical writes - events/jobs for async integration - no business rules in Blade/React ## 17.2 TypeScript/React - TypeScript strict mode - functional components - typed props - no `any` without documented reason - server-derived truth for authorization - deterministic SSR - no browser-only APIs during server render - accessible native elements first - reusable primitives - no company content embedded in components ## 17.3 SQL/data - migrations reviewed - indexes for query/filter fields - avoid N+1 - foreign keys - soft delete only where business/audit need justifies it - immutable activity log - protect personal/private application records --- # 18. AI prompt patterns ## 18.1 Feature implementation prompt ```text Implement DEV-123 for REQ-013. Read: - design.md §20.2 - design.md §11.7 - agents.md §§5,12 Objective: Prevent any confidential project detail from being publicly rendered unless publication_approved is true and the approved visibility fields permit it. Constraints: - Laravel policy and query scope must enforce this. - React must not receive suppressed data. - Add negative backend tests and Playwright coverage. - Do not change unrelated project fields. ``` ## 18.2 Debug prompt ```text Diagnose BUG-231. Public project pages occasionally show a hydration mismatch. Read design.md §6.3 and agents.md §6. Reproduce first, add a regression test, identify the nondeterministic value, fix only the root cause, and report the affected SSR components. ``` ## 18.3 Documentation prompt ```text Update documentation for the new Media Replace API. Keep design.md requirement IDs intact. Document request/response shape in docs/api. If the behavior changes a requirement or architecture decision, flag it rather than silently editing the requirement. ``` --- # 19. Cross-team handoffs ## 19.1 Backend → Frontend contract Before frontend implementation of a domain resource: - response shape documented - validation errors standardized - authorization behavior known - pagination/filter syntax known - media URLs/access policy known ## 19.2 Frontend → QA handoff Provide: - requirements IDs - route(s) - expected responsive behavior - accessibility notes - test account role if admin - edge cases ## 19.3 CMS → Content Manager handoff Provide: - module user guide - permission scope - publication workflow - required fields - media requirements - preview instructions - rollback instructions ## 19.4 DevOps → QA handoff Provide: - environment URL - release commit - feature flags - known non-production integration limitations - logs/monitoring access appropriate to QA --- # 20. Security incident workflow If a security issue is discovered: 1. Mark confidential/security issue. 2. Notify Tech Lead + Security Reviewer. 3. Avoid posting exploit details in public channels. 4. Reproduce safely. 5. Determine data exposure. 6. Patch in protected branch. 7. Add regression test. 8. Rotate affected credentials if needed. 9. Deploy under emergency process. 10. Document incident and follow-up. AI agents must not independently publish vulnerability details. --- # 21. Data migration/content import workflow For the initial 50–100 projects: 1. Define import template. 2. Validate client-approved fields. 3. Map sector/service taxonomy. 4. Attach approved media. 5. Mark confidentiality. 6. Dry-run import. 7. Report validation failures. 8. Import as draft. 9. Department review. 10. Management/final approval. 11. Publish. Never bulk-publish imported projects automatically. --- # 22. Milestone ownership and success metrics ## Phase 0 — validation/bootstrap | Role | Delivery checkpoint | |---|---| | Tech Lead | Architecture confirmed; ADR baseline | | Backend | Laravel/auth/database boots | | Frontend | React/Inertia SSR boots | | DevOps | CI + staging baseline | | QA | Test strategy established | | PM | Open items/dependencies logged | **Exit:** representative SSR page works and CI is green. ## Phase 1 — CMS foundation | Role | Delivery checkpoint | |---|---| | CMS | Page builder, menus, media, settings, workflow | | Backend | RBAC/revisions/audit | | Frontend | CMS shell + public design system | | QA | publish/edit permission tests | | Content | editorial workflow rehearsal | **Exit:** editor creates → approver approves → page SSR-publishes without code. ## Phase 2 — corporate modules **Exit:** all corporate launch modules are CMS editable and SSR rendered. ## Phase 3 — portfolio **Exit:** project filters, media and confidentiality controls pass functional/security tests. ## Phase 4 — engagement **Exit:** enquiries, RFP, appointments and notifications pass E2E; private files protected. ## Phase 5 — careers/tenders **Exit:** HR/tender roles and workflows verified. ## Phase 6 — integrations/performance **Exit:** Lighthouse targets achieved on representative pages or documented blockers are approved; production integrations configured where credentials exist. ## Phase 7 — QA/UAT **Exit:** no P0/P1 defects; browser/accessibility/security acceptance complete. ## Phase 8 — launch **Exit:** production smoke tests pass, backups/monitoring active, handover complete. ## Phase 9 — support **Metrics:** - uptime meets target - security updates timely - backup success monitored - incident response SLA met - no recurring critical defects --- # 23. Role scorecards ## Frontend Engineer - SSR correctness: 100% required routes - hydration errors: 0 - public E2E pass: 100% critical flows - accessibility: no launch-blocking AA issue - business-content hardcoding: 0 ## Backend Engineer - authorization on admin writes: 100% - backend suite: green - protected-file unauthorized access: 0 - failed queue jobs visible/retriable: 100% - integration errors do not block local website persistence ## CMS Developer - editable business content: 100% - workflow actions audit logged: 100% - theme customization requires code changes: 0 for approved tokens/options - content-manager UAT completion: pass ## DevOps - automated deployment: pass - rollback rehearsal: pass - backup success: ≥99% scheduled runs - restore drill: ≤4h target - production secret leakage: 0 ## QA - critical requirement coverage: 100% - P0/P1 at launch: 0 - browser matrix: pass - hydration warning coverage: pass - release evidence complete: 100% ## Content Manager - launch page completeness: 100% - required project approvals: 100% - image alt text: 100% meaningful content images - SEO metadata completeness: 100% priority pages --- # 24. Change-control workflow ```mermaid flowchart LR R[Requirement Gap / Change] --> I[Create Change Issue] I --> IMP[Assess Impact] IMP --> PO[Business Approval] PO --> DOC[Update design.md] DOC --> TASK[Update Implementation Tasks] TASK --> CODE[Code + Tests] CODE --> QA[QA] QA --> REL[Release] ``` Change issue must include: - old behavior - new behavior - reason - source/authority - requirement IDs - data impact - security impact - schedule/cost impact - migration need - acceptance criteria --- # 25. Release management Release candidate requires: - all milestone issues complete - CI green - QA sign-off - security sign-off - content approval - migration plan - rollback plan - backup verified - monitoring active - release notes - production approver Post-release: - smoke test - logs check - queue check - SSR health check - top routes check - form email check - analytics check - CWV observation --- # 26. Documentation maintenance rules 1. Every merged behavior change updates docs if externally visible or architecturally relevant. 2. `design.md` version increments for approved requirement/architecture changes. 3. `agents.md` version increments for process/role changes. 4. ADRs are append-only; supersede rather than erase history. 5. Release notes reference commit/tag and requirement IDs. 6. Examples use fake/sanitized data. 7. Broken internal links are CI failures when documentation tooling is available. --- # 27. Quality escalation thresholds Immediate escalation: - authentication bypass - authorization bypass - private CV/project file exposure - data loss - production outage - public confidential project content - corrupted migration - repeatable XSS/SQL injection - secrets committed Release blocker: - hydration error on core route - P1 form failure - WCAG blocker on primary navigation/forms - core browser incompatibility - CMS cannot edit a required public content area - backup/restore unverified - Lighthouse far below target without accepted exception --- # 28. Open-item ownership | Open item | Default owner | Required approver | |---|---|---| | OI-001 Corporate chronology | Content Manager / PM | Project Sponsor | | OI-002 Legal text | PM | Client legal/management | | OI-003 ERP/CRM API | Backend/Integration Lead | Client ICT/management | | OI-004 Project dataset | Content Manager | Department Heads / management | | OI-005 Project media approval | Portfolio Manager | Client/management | | OI-006 Brand guide | Frontend/Design | Project Sponsor | | OI-007 SMTP | DevOps | Client ICT | | OI-008 CAPTCHA | DevOps/Security | Tech Lead | | OI-009 Production infra | DevOps | Tech Lead/PM | | OI-010 Contact details | Content Manager | GGMP | | OI-011 M365 access | Integration Lead | Client ICT | --- # 29. Machine-readable task example ```yaml task: id: FE-042 title: Build SSR project detail template milestone: phase-3 owner_role: frontend_engineer requirement_ids: - REQ-003 - REQ-011 - REQ-013 design_sections: - "6.1" - "20" depends_on: - BE-037 - CMS-021 acceptance: - "Project page returns meaningful SSR HTML." - "No confidential fields are rendered." - "No hydration warnings." - "Gallery keyboard navigation passes." - "Project schema fields are sourced from CMS." test_commands: - "npm test" - "npx playwright test" reviewers: - frontend_lead - qa ``` --- # 30. Validation checklist ## Roles - [x] Product/business owner responsibilities defined. - [x] Project management responsibilities defined. - [x] Technical lead responsibilities defined. - [x] Frontend role defined. - [x] Backend role defined. - [x] CMS role defined. - [x] DevOps role defined. - [x] QA role defined. - [x] Security role defined. - [x] Content role defined. ## AI agents - [x] Code generation scope defined. - [x] Debugging scope defined. - [x] Documentation scope defined. - [x] Review/test scope defined. - [x] Access controls defined. - [x] Production/secrets restrictions defined. - [x] Machine-readable task envelope defined. ## Collaboration - [x] Daily sync protocol defined. - [x] Async status format defined. - [x] Issue workflow defined. - [x] PR template defined. - [x] Review levels defined. - [x] CMS approval chain defined. - [x] Cross-team handoffs defined. - [x] Security incident process defined. ## Knowledge management - [x] Repository documentation structure defined. - [x] ADR process defined. - [x] Requirement update process defined. - [x] Version-control conventions defined. - [x] Documentation maintenance rules defined. ## Success metrics - [x] Role scorecards defined. - [x] Milestone exit criteria defined. - [x] Quality escalation thresholds defined. - [x] Release gates defined. - [x] Open-item ownership defined. ## Sufficiency - [x] Tasks can be scoped directly from requirement IDs in `design.md`. - [x] Human and AI agents have explicit execution boundaries. - [x] Code cannot be merged without requirements/tests/review. - [x] CMS content publication is governed independently from code deployment. - [x] Requirement changes cannot silently bypass the documentation. - [x] The operating model is sufficient to execute the full roadmap in `design.md` without additional process clarification.