# INVEETAIRE ## SPRINT 1 EXECUTION GUIDE | Field | Value | |-------|-------| | Document Type | Execution Guide | | Sprint | Sprint 1 — Core Utilities | | Version | 1.0 (Final) | | Status | Active | | Framework Baseline | commit `0275776` · tags `sprint0-baseline`, `framework-v1.0` | | Based On | AI.md v1.1 · AI_DEVELOPMENT_SYSTEM.md v1.0 · WORKFLOW.md · DBP v1.1 · SPRINT1_PLANNING.md | | Applies To | All AI Implementation Agents and Human Approvers contributing to Sprint 1 | > This document is the operational handbook for Sprint 1 execution. It complements — and does not replace — the governance documents. Any AI Implementation Agent must be able to follow this guide from a cold start, with no prior session context. --- ## 1. Purpose This guide defines **how** Sprint 1 is executed. It translates the approved architecture, governance rules, and sprint plan into a concrete, step-by-step operational workflow that any AI Implementation Agent can follow immediately. Sprint 1 focuses on two simultaneous objectives: 1. **Implementation speed** — four focused tasks with clearly bounded scope, no design decisions required, and all prerequisites already in place from Sprint 0. 2. **Architecture quality** — the Sprint 0 kernel is frozen. Every Sprint 1 action must extend the framework without modifying it (except the one approved additive change to `MiddlewarePipeline.php`). This guide is the operational companion to `SPRINT1_PLANNING.md`. The planning document defines what will be built. This guide defines how it will be built. --- ## 2. Sprint 1 Scope ### 2.1 Objectives Sprint 1 delivers the Core Utilities layer: 1. A formal middleware contract (`MiddlewareInterface`) to replace the convention-only approach inherited from Sprint 0 2. A production-ready CSRF protection middleware (`CsrfMiddleware`) wired into the existing pipeline 3. A compiled CSS and JavaScript asset pipeline, eliminating the CDN dependency approved as a Sprint 0 deferral 4. Updated portal layouts referencing compiled local assets ### 2.2 Deliverables | Task ID | Deliverable | Output Files | |---------|-------------|-------------| | CORE-001 | Middleware interface contract | `app/core/MiddlewareInterface.php` | | CORE-002 | CSRF protection middleware | `app/middleware/CsrfMiddleware.php` | | CORE-003 | Compiled asset pipeline | `public/assets/css/app.css`, `public/assets/js/app.js` | | CORE-004 | Layout CDN replacement | `app/views/layouts/couple.php`, `admin.php`, `crew.php`, `public.php` (modified) | One additive modification to an existing kernel file is approved: `app/core/MiddlewarePipeline.php` receives an `instanceof MiddlewareInterface` check in CORE-001. This is the only permitted kernel modification in Sprint 1. ### 2.3 What Sprint 1 Does NOT Include The following are explicitly out of scope for Sprint 1. They must not be implemented, stubbed, or partially built: | Excluded Item | Assigned Sprint | |---------------|----------------| | Authentication (login, logout, password hashing) | Sprint 2 | | `AuthMiddleware` | Sprint 2 | | `RoleMiddleware` | Sprint 2 | | Session timeout enforcement | Sprint 2 | | User model or service | Sprint 2 | | Login/logout controllers or views | Sprint 2 | | Route additions beyond existing skeletons | Sprint 2+ | | Database schema or migrations | Sprint 2+ | | Any business domain feature | Future sprints | **No stub files** may be created for future middleware. `app/middleware/` will contain only `CsrfMiddleware.php` after Sprint 1. --- ## 3. Task Execution Workflow Every Sprint 1 task follows this exact sequence. No step may be skipped. ``` Task defined in SPRINT1_PLANNING.md | v AI reads all mandatory documents (Section 4) | v AI reviews repository state (verify Sprint 0 files present) | v Implementation Prompt issued by Human Approver | v AI Implementation Agent executes task | v AI performs self-review (Section 5 — After Coding checklist) | v Implementation Report produced (Section 9 format) | v Human Approver reviews implementation and report | v Architecture and code quality reviewed (Section 6 checklist) | v Human Approver gives explicit approval | v Human executes: git add | v Human executes: git commit -m "message" | v Human executes: git push | v AI writes implementation memory file (docs/ai/memory/) | v Human confirms memory file is committed | v Next task begins ``` **The loop does not restart until the memory file is committed.** An approved, committed task with no memory file is incomplete. --- ## 4. Mandatory Reading Before Every Task Every AI Implementation Agent must read the following documents **before writing a single line of code** in each session. This is non-negotiable. | Document | Location | Why It Must Be Read | |----------|----------|---------------------| | `AI.md v1.1` | `docs/ai/AI.md` | Defines all operational rules, stop conditions, and agent behavior | | `AI_DEVELOPMENT_SYSTEM.md v1.0` | `docs/04-governance/AI_DEVELOPMENT_SYSTEM.md` | Defines the governance framework within which all work occurs | | `WORKFLOW.md` | `docs/ai/WORKFLOW.md` | Defines the step-by-step workflow and Golden Rule (one task = one session) | | `DBP v1.1` | `docs/02-architecture/DBP_v1.1.md` | Defines every coding standard, naming convention, and architectural pattern | | `MIB v1.1` | `docs/02-architecture/MASTER_IMPLEMENTATION_BACKLOG_v1.1.md` | Contains the authoritative task definitions for Epic 0; Sprint 1 tasks are in the v1.0 `.docx` | | `SPRINT1_PLANNING.md` | `docs/02-architecture/SPRINT1_PLANNING.md` | Defines Sprint 1 scope, tasks, constraints, and risk register | | `SPRINT0_ARCHITECTURE_REVIEW.md` | `docs/02-architecture/SPRINT0_ARCHITECTURE_REVIEW.md` | Documents the frozen kernel, technical debt register, and Sprint 1 readiness verdict | | All `docs/ai/memory/` files | `docs/ai/memory/01_*.md` through `docs/ai/memory/19_*.md` | Provides complete Sprint 0 decision history; essential for understanding what was built and why | Additionally, before beginning any specific CORE task, the AI Implementation Agent must review the source files of the tasks that task depends on: | Task | Dependency Files to Review Before Starting | |------|--------------------------------------------| | CORE-001 | `app/core/MiddlewarePipeline.php` | | CORE-002 | `app/core/MiddlewareInterface.php`, `app/core/Csrf.php`, `app/core/Session.php`, `app/core/ErrorHandler.php` | | CORE-003 | All four layout files in `app/views/layouts/`, `public/assets/css/app.css`, `public/assets/js/app.js` | | CORE-004 | `public/assets/css/app.css`, `public/assets/js/app.js` (verify CORE-003 output first) | --- ## 5. Implementation Checklist ### 5.1 Before Coding - [ ] All mandatory documents read (Section 4) - [ ] All Sprint 0 memory files reviewed - [ ] Current repository state verified (correct branch, correct HEAD) - [ ] Dependency files for this task reviewed - [ ] "Files Expected" for this task identified and recorded - [ ] Acceptance criteria for this task identified and recorded - [ ] No documentation conflict detected (if conflict found: STOP — see Section 11) - [ ] No undocumented prerequisite missing (if missing: STOP — see Section 11) - [ ] All prerequisite tasks have been approved and committed before this task begins > **Dependency rule**: Implementation must never begin from an unapproved dependency. If a prerequisite task has not been committed to the repository, the current task does not begin. The dependency graph in `SPRINT1_PLANNING.md` defines the required completion order. ### 5.2 During Coding - [ ] Creating only files listed in "Files Expected" for this task - [ ] Not modifying any file outside this task's scope - [ ] Not modifying any frozen kernel file (exception: the approved additive change to `MiddlewarePipeline.php` in CORE-001 only) - [ ] Using PSR-4 namespace conventions (`App\Core\`, `App\Middleware\`) - [ ] Using PHP 7.4 compatible syntax only - [ ] Applying `escape_html()` to all view output - [ ] No business logic in middleware or controllers - [ ] Middleware is thin and single-purpose - [ ] No raw SQL anywhere (Sprint 1 has no database queries — this is a forward constraint) - [ ] Docblocks present on every class and public method ### 5.3 After Coding - [ ] All "Files Expected" are created - [ ] No additional files created - [ ] Acceptance criteria manually verified (each criterion) - [ ] PHP syntax validated (`php -l` on each new file) - [ ] No debug code (`var_dump`, `print_r`, `die`, `exit` outside error handlers) - [ ] No `TODO` comments in committed code - [ ] Implementation Report drafted (Section 9 format) ### 5.4 Before Approval - [ ] Implementation Report complete and accurate - [ ] All acceptance criteria listed with pass/fail/note status - [ ] Proposed commit message included in report - [ ] Any deviation from specification documented in "Documentation Deviations" section - [ ] Any discovered architectural finding flagged for DRP review ### 5.5 Before Git - [ ] Human Approver has given **explicit** approval in the current session message - [ ] No pending corrections from the Human Approver - [ ] Commit message reviewed and confirmed - [ ] `git status` verified — only expected files staged - [ ] Working tree contains only expected modifications > **Clean tree rule**: `git status` must show only files belonging to the current task. If unrelated modifications appear, stop and resolve before committing. Never commit files outside the current task's "Files Expected" list. --- ## 6. Review Checklist The Human Approver applies this checklist before approving each task. ### 6.1 Architecture - [ ] No kernel file modified except the approved `MiddlewarePipeline.php` change (CORE-001 only) - [ ] New files are in the correct directory (`app/core/` or `app/middleware/`) - [ ] Class namespace matches PSR-4 mapping (`App\Core\` → `app/core/`, `App\Middleware\` → `app/middleware/`) - [ ] New class does not introduce dependencies on future sprint modules - [ ] Extension points used correctly (interface implemented, pipeline unmodified except guard) ### 6.2 Coding Standards - [ ] Naming conventions follow DBP v1.1 Chapter 3 - [ ] Class names are PascalCase; methods are camelCase - [ ] Constants are UPPER_SNAKE_CASE - [ ] All strings are single-quoted unless interpolation is required - [ ] No closing `?>` PHP tag in files - [ ] UTF-8 encoding, Unix line endings - [ ] Docblocks present with `@param`, `@return`, and `@ref` cross-references ### 6.3 Security - [ ] All view output passes through `escape_html()` - [ ] No raw user input echoed directly - [ ] CSRF validation occurs before any POST action is processed (CORE-002 verification) - [ ] No `eval()`, `exec()`, or dynamic includes - [ ] Session not accessible directly from middleware (uses `Session::get()`) ### 6.4 Scope - [ ] Implementation matches "Files Expected" exactly — no more, no fewer files - [ ] No stub files created for future tasks - [ ] No route additions (route files remain as Sprint 0 skeletons) - [ ] No database queries introduced ### 6.5 Files Expected - [ ] Every file in "Files Expected" exists - [ ] No file exists that is not in "Files Expected" - [ ] File paths match the specification exactly (case-sensitive) ### 6.6 Acceptance Criteria - [ ] Every acceptance criterion is listed in the Implementation Report - [ ] Every criterion is marked: `PASS`, `FAIL`, or `N/A` with note - [ ] No criterion is omitted - [ ] Any failing criterion is addressed before approval ### 6.7 Documentation Deviations - [ ] Any deviation from the specification is documented - [ ] Any discovered architectural gap is flagged for DRP review - [ ] No deviation is silently resolved --- ## 7. Git Workflow ### 7.1 Standard Commit Sequence Git operations are performed by the Human Approver only. The AI Implementation Agent proposes the commit message; it does not execute any Git command unless explicitly instructed. ``` Human executes: git status (verify only expected files are modified/added) | v Human executes: git add (never: git add . unless all changes are verified) | v Human executes: git commit -m "type: description (TASK-ID)" | v Human executes: git push ``` ### 7.2 Commit Message Format ``` type: description (TASK-ID) Types: feat — new file or feature fix — bug correction docs — documentation only refactor — code change with no behavior change style — formatting only Examples: feat: add MiddlewareInterface contract (CORE-001) feat: implement CsrfMiddleware (CORE-002) feat: compile Tailwind CSS and Alpine.js assets (CORE-003) refactor: replace CDN script tags with local assets in layouts (CORE-004) ``` One task = one commit. Tasks are not batched together. ### 7.3 Branch Policy Sprint 1 work is committed directly to `main`. Feature branches are not required unless the Human Approver decides otherwise. This is consistent with the Sprint 0 workflow. ### 7.4 Tag Policy After all Sprint 1 tasks are complete and verified, the Human Approver applies a sprint completion tag: ``` git tag sprint1-complete git push origin sprint1-complete ``` Tags are applied by the Human Approver only. The AI Implementation Agent proposes the tag name; it does not execute the tag command. ### 7.5 AI Git Authorization **AI agents do not execute Git write operations unless explicitly authorized.** The phrase "implement CORE-XXX" does not authorize Git operations. The phrase "commit and push" or "run git commit" in the current session message authorizes the specific operation. Read-only commands (`git status`, `git log`, `git diff`) may be run freely to verify state. --- ## 8. Prompt Standards Every Sprint 1 implementation prompt must follow this structure. ### 8.1 Mandatory Sections Every prompt must contain all of the following: | Section | Content | |---------|---------| | **Task Identity** | Task ID (CORE-XXX), task name, sprint | | **Mandatory References** | Complete list of documents to read before starting | | **Objective** | One-paragraph description of what the task builds | | **Files Expected** | Exact table: Type (New/Modified) \| Path | | **Acceptance Criteria** | Numbered, verifiable list of pass/fail conditions | | **Architectural Constraints** | Specific constraints for this task (frozen files, approved exceptions) | | **Explicit Prohibitions** | What must NOT be created, modified, or implemented in this session | ### 8.2 Forbidden Prompt Content Prompts must NOT include: - Open-ended design questions (all design decisions are pre-approved) - Permission to deviate from "Files Expected" without explicit approval - Instructions that contradict a higher-authority document - Instructions to execute Git commands (unless explicitly intended) - Multiple task IDs (one task per prompt) ### 8.3 Expected Output Every implementation prompt must produce: 1. The files listed in "Files Expected" — no more, no fewer 2. An Implementation Report (Section 9 format) 3. A proposed commit message 4. A proposed memory file content for the Human Approver to commit --- ## 9. Implementation Report Standard Every completed task requires an Implementation Report in the following exact format. --- **IMPLEMENTATION REPORT** **Task**: CORE-XXX — [Task Name] **Sprint**: Sprint 1 — Core Utilities **Date**: YYYY-MM-DD --- **1. Implementation Summary** One to three paragraphs describing what was built, what approach was taken, and any implementation decisions made. Reference the specification where relevant. If the implementation is identical to the specification, state that explicitly. --- **2. Files Created** | File | Type | Lines | |------|------|-------| | `path/to/file.php` | New | N | --- **3. Files Modified** | File | Type | Change Description | |------|------|-------------------| | `path/to/existing.php` | Modified | Brief description of what changed | If no files were modified: `None.` --- **4. Acceptance Criteria** | # | Criterion | Status | Note | |---|-----------|--------|------| | 1 | [Criterion from specification] | PASS / FAIL / N/A | [Note if not PASS] | All criteria must be listed. No criterion may be omitted. --- **5. Definition of Done** | Item | Status | |------|--------| | All "Files Expected" created | ✅ / ❌ | | No files created outside "Files Expected" | ✅ / ❌ | | No kernel files modified (except approved exception) | ✅ / ❌ | | PHP syntax validated | ✅ / ❌ | | No debug code | ✅ / ❌ | | No TODO comments | ✅ / ❌ | | Docblocks present | ✅ / ❌ | | Output escaping applied | ✅ / N/A | --- **6. Proposed Commit** ``` feat: [description] (CORE-XXX) ``` Files to stage: - `path/to/file1.php` - `path/to/file2.php` --- **7. Documentation Deviations** Any deviation from the specification, any architectural discovery, or any gap in documentation must be documented here. If the implementation exactly matches the specification: `None.` If a deviation occurred, document: - What the specification says - What was implemented instead - Why - Whether a Design Revision Pack entry is recommended --- ## 10. Quality Gates ### 10.1 Per-Task Gate Each task must pass its per-task gate before the Human Approver gives approval. | Gate Item | Verified By | |-----------|------------| | All Section 5.3 (After Coding) items checked | AI Implementation Agent | | All Section 6 (Review Checklist) items checked | Human Approver | | Implementation Report complete | AI Implementation Agent | | No failing acceptance criteria | Both | | No unauthorized kernel modification | Human Approver | **A task that fails any gate item is not approved.** ### 10.2 Per-Sprint Gate All four CORE tasks must be complete before the sprint gate is checked. | Gate Item | Verified By | |-----------|------------| | CORE-001 approved and committed | Human Approver | | CORE-002 approved and committed | Human Approver | | CORE-003 approved and committed | Human Approver | | CORE-004 approved and committed | Human Approver | | TD-001 (MiddlewareInterface) resolved | Human Approver | | TD-004 (TailwindCSS CDN) resolved | Human Approver | | No new undocumented technical debt | Human Approver | | Memory files written for all 4 tasks | AI Implementation Agent | | Memory files committed | Human Approver | | Sprint 1 Architecture Review produced | AI Documentation Agent | | Sprint 1 Architecture Review approved | Human Approver | ### 10.3 Before Sprint Close Before Sprint 1 is declared complete: | Gate Item | Verified By | |-----------|------------| | Sprint gate checklist above fully verified | Human Approver | | `docs/ai/memory/` contains memory files for all Sprint 1 tasks | Human Approver | | Design Revision Pack produced if any deviations occurred | AI Documentation Agent | | All documentation synchronized with approved DRP | AI Documentation Agent | | Sprint completion tag applied: `sprint1-complete` | Human Approver | ### 10.4 Before Any Future Sprint Sprint 2 may not begin until: - Sprint 1 per-sprint gate is fully verified - Human Approver has explicitly declared Sprint 1 complete - Sprint 2 Planning document is produced --- ## 11. Handling Documentation Conflicts A documentation conflict occurs when two documents contain contradictory instructions, requirements, or constraints. Conflicts must never be resolved autonomously by the AI Implementation Agent. ### 11.1 Conflict Protocol ``` STOP — halt implementation immediately | v Identify: - Document A (higher authority): exact quote and location - Document B (lower authority): exact quote and location - The specific conflict: what precisely contradicts what | v Reference the Documentation Authority Hierarchy: AI.md > ADR > MIB > Sprint Execution Plan > Prompt > Implementation | v Report to Human Approver: - Both documents identified - The conflict described precisely - Two or more resolution options listed - A recommendation (if the hierarchy clearly resolves it) | v Wait — do not implement anything until explicit approval is received | v Document the resolution in the implementation memory file | v Determine if a Design Revision Pack entry is needed: - If the conflict reveals a documentation error: DRP entry recommended - If the conflict was a misreading: document clarification in memory | v Resume implementation with the approved resolution ``` ### 11.2 Common Sprint 1 Conflict Scenarios | Scenario | Correct Action | |----------|---------------| | Prompt says to create a file not in "Files Expected" | The MIB governs. Stop and report the conflict. | | Prompt says to modify a frozen kernel file | AI.md and SPRINT1_PLANNING.md govern. Stop and report. | | CORE-002 prompt references a `Csrf` method that does not exist | Stop. Verify `app/core/Csrf.php`. Report the missing method. | | CORE-003 build step fails due to missing Node.js | Not a documentation conflict. Document in memory. Human Approver decides how to proceed. | --- ## 12. Handling AI Account Rotation ### 12.1 Context A Sprint 1 implementation session may be interrupted by quota exhaustion, a network timeout, or a deliberate pause. Development may resume on a different AI account, a different day, or with a different AI model. This section defines how continuity is maintained. ### 12.2 Repository as Source of Truth **The repository contains everything a new session needs.** No session-specific memory is required. When a new session begins: ``` New session opened (any account, any model) | v Read: AI.md, AI_DEVELOPMENT_SYSTEM.md, WORKFLOW.md | v Read: SPRINT1_PLANNING.md, SPRINT1_EXECUTION_GUIDE.md | v Read: all docs/ai/memory/ files (chronological order) | v Review current repository state: git log --oneline -10 git status | v AI produces written context summary: - Sprint 1 tasks: which are complete, which are in progress, which are pending - Current task: what has been implemented, what remains - Next action | v Human Approver confirms or corrects the summary | v Implementation resumes ``` ### 12.3 Memory Files Memory files in `docs/ai/memory/` are the primary continuity mechanism. Each completed task produces one memory file. A session that ended mid-task may have no memory file yet — in that case, the repository state (which files exist, their content) is the record of what was done. Before resuming a mid-task session, the AI Implementation Agent must: 1. Read all existing memory files 2. Review all files relevant to the current task 3. Determine exactly where implementation stopped 4. Confirm with the Human Approver before continuing ### 12.4 Response Archive Full implementation responses (not just summaries) are stored in `docs/ai/memory/` alongside the memory summary files. **Memory Files** contain: - Compressed decision summaries - Implementation decisions and their rationale - Key architectural findings - Next session notes **Response Archive** (full response files) contains: - Complete implementation transcripts - Full reasoning chains - Detailed reports and self-review output - Useful for deep investigation of past decisions Normal session recovery should always begin with Memory Files. Response Archives are consulted only when additional detail is required. ### 12.5 Context Recovery Checklist When recovering from an interrupted session: - [ ] All mandatory documents read (Section 4) - [ ] All existing memory files read (Memory Files first, Response Archive only if detail is needed) - [ ] Repository state reviewed (`git log`, `git status`) - [ ] Current task's "Files Expected" identified - [ ] Files already created in current task identified - [ ] Context summary produced and confirmed by Human Approver ### 12.6 Model Independence Sprint 1 implementation does not depend on any specific AI model. The repository, documentation, memory files, and this guide provide complete context for any AI Implementation Agent capable of reading documentation and following instructions. A switch from one AI provider to another mid-sprint loses nothing, provided: - All memory files are committed - All implementation is committed - This guide and `SPRINT1_PLANNING.md` are read at the start of the new session ### 12.7 Memory File Naming Convention Memory files follow a sequential numbering scheme that is chronological and project-wide. Numbering **never resets** between sprints. ``` Sprint 0 memory files: 01_project_understanding.md 02_sprint0_execution_plan.md 03_init001.md 04_init002.md ... 18_sprint1_planning.md 19_ai_development_review.md Sprint 1 memory files continue the sequence: 20_core001.md 21_core002.md 22_core003.md 23_core004.md ``` The number prefix reflects chronological creation order across the **entire project**, not within a sprint. The task ID appears in the filename but does not determine the number. If a task requires multiple memory entries (e.g., a conflict arose mid-task), the same number prefix is reused with a descriptive suffix: ``` 20_core001.md 20_core001_conflict.md ``` Memory file naming follows the convention established during Sprint 0. See `docs/ai/memory/README.md` for the full convention reference. --- ## 13. Sprint Completion ### 13.1 When Sprint 1 Is Complete Sprint 1 is complete when all of the following are true, verified, and explicitly confirmed by the Human Approver: 1. **All four CORE tasks** (CORE-001 through CORE-004) are implemented, approved, and committed 2. **TD-001 resolved**: `MiddlewareInterface.php` exists; `MiddlewarePipeline.php` contains the `instanceof` guard 3. **TD-004 resolved**: All four portal layouts use local CSS/JS assets; no CDN `