# INVEETAIRE
## DESIGN REVISION PACK
### Version 2.0

| Field | Value |
|-------|-------|
| Version | 2.0 |
| Status | Pending Review |
| Document Type | Design Revision Pack |
| Supersedes | Design Revision Pack v1.0 |
| Produced After | Sprint 0 — Project Initialization (INIT-001 through INIT-012) |
| Date | 2026-06-30 |

---

## Purpose

This document records every architectural decision, documentation conflict, approved prerequisite, dependency correction, execution order correction, and governance improvement identified during the Sprint 0 implementation.

It supersedes Design Revision Pack v1.0, which recorded pre-implementation architectural improvements identified during the planning phase.

**Scope:** Sprint 0 only (INIT-001 through INIT-012 inclusive).

**Rules:**

- Every revision listed here was either explicitly approved during Sprint 0 or confirmed by the user resolving a documented conflict.
- Rejected proposals are omitted.
- No implementation details or code.
- No invented revisions.
- If evidence of a finding was uncertain, the revision was omitted.

No official documentation shall be modified until every revision listed in this document has been reviewed and approved.

---

## Revision Summary

| ID | Title | Source Task | Affected Documents | Status |
|----|-------|-------------|-------------------|--------|
| REV-010 | Execution Order Is Independent of INIT Task Numbers | INIT-001 through INIT-012 | MIB, Sprint 0 Plan | Approved |
| REV-011 | INIT-012 Execution Position and Validation-Only Responsibility | INIT-008, INIT-012 | MIB, DBP, Sprint 0 Plan | Approved |
| REV-013 | Middleware Scope Boundary — Pipeline Engine Only in Sprint 0 | INIT-009 | MIB, Sprint 0 Plan | Approved |
| REV-015 | INIT-011 Task Name Conflict Resolved in Favour of Sprint 0 Plan | INIT-011 | Sprint 0 Plan | Approved |
| REV-016 | escape_html() Formalized as Mandatory View Output Contract | INIT-011 | MIB, TCS, DBP | Approved |
| REV-017 | Portal Layout Declaration Is a Controller Responsibility | INIT-008, INIT-011 | DBP, MIB, TCS | Approved |
| REV-018 | SESSION_INACTIVITY_TIMEOUT Formalized as a Required Configuration Key | INIT-002 | MIB, DBP | Approved |
| REV-019 | config() Root Resolution Pattern Formalized for Pre-Bootstrap Context | INIT-005 | DBP, TCS | Approved |
| REV-020 | BaseModel::count() Formalized as a Core Data Access Primitive | INIT-008 | MIB, DBP | Approved |
| REV-022 | CLI Validation Test Scaffold Pattern Formalized | INIT-006, INIT-007, INIT-008 | TCS, AI.md | Approved |
| REV-023 | Documentation Authority Hierarchy Formalized | Sprint 0 (all tasks) | AI.md, WORKFLOW.md, PROJECT.md | Approved |

---

## Revisions

---

### REV-010 — Execution Order Is Independent of INIT Task Numbers

**Background**

The Sprint 0 Master Implementation Backlog (MIB) assigns task IDs in the sequence INIT-001 through INIT-012. The numeric order implies this is the implementation sequence.

**Finding**

The correct dependency-safe execution order is not the same as the numeric INIT order. Specifically:

- INIT-005 must precede INIT-003 (Bootstrap depends on `env()` and `config()`)
- INIT-003 must precede INIT-004 (`.htaccess` depends on the front controller existing)
- INIT-012 must precede INIT-009 (database connection must be validated before the middleware pipeline is wired)

The correct Sprint 0 execution sequence, as recorded in the Sprint 0 Execution Plan and confirmed by the Task Tracker, is:

```
INIT-001 → INIT-002 → INIT-005 → INIT-003 → INIT-004
         → INIT-006 → INIT-007 → INIT-008 → INIT-012
         → INIT-009 → INIT-010 → INIT-011
```

**Approved Decision**

The execution order published in the Sprint 0 Task Tracker is authoritative. The numeric INIT ID is an identifier, not a sequencing instruction. Future MIB revisions must clarify this distinction explicitly by adding a dedicated Execution Sequence section separate from task ID numbering.

**Affected Documents**

- MIB v1.0 — Add explicit "Execution Sequence" section distinct from task ID numbering
- Sprint 0 Execution Plan — Already reflects correct order; no change required

**Implementation Impact**

None. The Sprint 0 implementation followed the correct order as defined in the Task Tracker.

**Migration Required**

No.

**Risk**

Low. Affects documentation clarity only.

**Status**

Approved.

---

### REV-011 — INIT-012 Execution Position and Validation-Only Responsibility

**Background**

The Sprint 0 Execution Plan placed INIT-012 (Database Connection Validation) after INIT-010 (Session) in its dependency graph. The plan also described INIT-012 as a task that "creates/completes" `app/core/Database.php` and validates `config/database.php`.

**Finding**

Two corrections were required:

**1. Execution position.** INIT-012 must execute immediately after INIT-008 (Database singleton created) and before INIT-009 (Middleware pipeline). The Sprint 0 plan's dependency graph showed INIT-008 → INIT-009 directly, bypassing the validation gate. The Task Tracker and actual implementation both placed INIT-012 at position 9, between INIT-008 and INIT-009, which is the correct order.

```
Incorrect (Sprint 0 plan): INIT-008 → INIT-009
Correct (Task Tracker):    INIT-008 → INIT-012 → INIT-009
```

**2. Validation-only responsibility.** When INIT-012 was executed, `app/core/Database.php` was already fully implemented by INIT-008 — not as a skeleton, but as a production-complete singleton. INIT-012's role was therefore exclusively live validation against the MariaDB instance. No source code changes were required.

Confirmed live:
- `SELECT 1` → result 1
- charset → utf8mb4
- `PDO::ATTR_ERRMODE` → ERRMODE_EXCEPTION
- `PDO::ATTR_DEFAULT_FETCH_MODE` → FETCH_ASSOC
- Singleton identity: same object instance on repeated calls
- Real prepared statements execute correctly

**Approved Decision**

The corrected execution order `INIT-008 → INIT-012 → INIT-009` is authoritative. INIT-012 is a validation task, not an implementation task. The MIB description "creates/completes" must be revised to "validates the database connection layer established in INIT-008." No new files are created by INIT-012 when INIT-008 has been executed first.

**Affected Documents**

- Sprint 0 Execution Plan — Correct dependency graph: INIT-008 → INIT-012 → INIT-009
- MIB v1.0 — INIT-012 dependency list: add INIT-008 as explicit prerequisite; note INIT-009 depends on INIT-012
- MIB v1.0 — INIT-012 description: change "creates/completes" to "validates"
- DBP — INIT-012 section: note "no new files when INIT-008 precedes it"

**Implementation Impact**

None. Already implemented and validated in the correct order.

**Migration Required**

No.

**Risk**

Low. Documentation only.

**Status**

Approved.

---

### REV-013 — Middleware Scope Boundary — Pipeline Engine Only in Sprint 0

**Background**

The Sprint 0 Execution Plan (TASK 10 — INIT-009) listed seven files under "What this creates":

| File | Purpose |
|------|---------|
| `app/core/MiddlewarePipeline.php` | Pipeline engine |
| `app/middleware/AuthMiddleware.php` | Auth guard stub |
| `app/middleware/RoleMiddleware.php` | Role guard stub |
| `app/middleware/CsrfMiddleware.php` | CSRF guard stub |
| `app/middleware/WorkspaceMiddleware.php` | Workspace isolation stub |
| `app/middleware/GuestMiddleware.php` | Guest code resolver stub |
| `app/middleware/SupportMiddleware.php` | Support overlay stub |

The plan noted: *"At Sprint 0, most middleware will redirect to a placeholder or return a stub response, since Auth module (sessions/user records) does not exist yet."*

**Finding**

Stubs that reference undefined Auth structures produce dead code that will be entirely replaced when the implementing sprint arrives. The six concrete middleware classes have no business logic at Sprint 0, reference types that do not exist, and provide no architectural value before their implementing module is built. Creating them prematurely violates the principle of implementing only what can be fully specified.

The revised INIT-009 task scope restricted Sprint 0 to the pipeline engine only. All six concrete middleware classes were explicitly deferred.

**Approved Decision**

The Sprint 0 INIT-009 "Files Expected" is reduced to one file: `app/core/MiddlewarePipeline.php`.

The six concrete middleware classes are deferred to their implementing sprints:

| File | Implementing Sprint |
|------|-------------------|
| `CsrfMiddleware.php` | Sprint 1 (Core Utilities) |
| `AuthMiddleware.php` | Sprint 2 (Authentication) |
| `RoleMiddleware.php` | Sprint 2 (Authentication) |
| `WorkspaceMiddleware.php` | Sprint 3 (Workspace) |
| `GuestMiddleware.php` | Sprint 4/5 (Guest) |
| `SupportMiddleware.php` | Sprint 13 (Support Mode) |

`app/middleware/` remains empty (`.gitkeep` only) after Sprint 0. The pipeline engine is in place and ready to accept middleware classes the moment any implementing sprint creates them.

**Affected Documents**

- MIB v1.0 — INIT-009 "Files Expected": reduce to `MiddlewarePipeline.php` only
- MIB v1.0 — Each concrete middleware file: assign to the "Files Expected" of its implementing sprint
- Sprint 0 Execution Plan — TASK 10: update "What this creates" table accordingly

**Implementation Impact**

No concrete middleware logic may be introduced until the implementing sprint creates its respective file. Route middleware arrays may reference class names that do not yet exist — the pipeline will log and gracefully handle missing classes.

**Migration Required**

No. The `app/middleware/` directory exists and is correctly empty.

**Risk**

Low. The pipeline engine is operational. Middleware class resolution is guarded against missing classes.

**Status**

Approved.

---

### REV-015 — INIT-011 Task Name Conflict Resolved in Favour of Sprint 0 Plan

**Background**

The Sprint 0 Execution Plan (TASK 12 — INIT-011) defines the task as *"Create View Renderer and Layout System"* with nine files expected. The initial task prompt issued for INIT-011 was titled *"Logging Finalization"* and described verifying Logger integration points.

**Finding**

A direct conflict existed between two documents:

| Document | INIT-011 Definition |
|----------|---------------------|
| Sprint 0 Execution Plan (lines 388–420) | "Create View Renderer and Layout System" — 9 files |
| Initial INIT-011 task prompt | "Logging Finalization" — no implementation files |

Per the conflict resolution rule (REV-023), implementation was stopped and the conflict was reported. The user confirmed that the Sprint 0 Execution Plan is authoritative. A revised prompt (`13_INIT011_REVISED.md`) was issued with the correct task name and scope.

Additionally, `app/core/Logger.php` was implemented to full production specification during INIT-006, not as a skeleton. All Logger integration points were already wired by the time INIT-011 was reached. A "Logging Finalization" task would have been a no-op. This further confirms that the "Logging Finalization" prompt was a documentation error, not a scope change.

**Approved Decision**

INIT-011 is definitively "Create View Renderer and Layout System" per the Sprint 0 Execution Plan. The "Logging Finalization" designation was a documentation error in the initial task prompt. Logger.php is complete after INIT-006; no standalone finalization task is required in Sprint 0. Future logging enhancements (Auth context, structured log levels, log channels) are Sprint 1+ responsibilities.

**Affected Documents**

- Sprint 0 task prompt library — `12_INIT011.md` is superseded by `13_INIT011_REVISED.md`
- MIB v1.0 — Remove or retitle any reference to a "Logging Finalization" task; INIT-006 is the complete logging implementation for Sprint 0
- Sprint 0 Execution Plan — Clarify that INIT-006 creates Logger.php to completion, not as a skeleton requiring finalization

**Implementation Impact**

None. The correct 9-file view system was implemented after the conflict was resolved.

**Migration Required**

No.

**Risk**

Low. Documentation error only; no code impact.

**Status**

Approved and resolved.

---

### REV-016 — escape_html() Formalized as Mandatory View Output Contract

**Background**

The Sprint 0 Execution Plan (INIT-011 section) states: *"Output escaping rule: Every `echo` in a view must use `escape_html()`. No raw `echo $_var` ever."*

**Finding**

The function `escape_html()` was not defined anywhere in the codebase at the start of INIT-011 and was not listed under the "Files Expected" of any INIT task. The output escaping rule mandates its use in every layout and view component, making it a required implicit prerequisite of INIT-011. Without it, the documented escaping rule cannot be satisfied.

Implementation was stopped and the gap was reported. The user approved the formalization of `app/helpers/escape_html.php` as an implicit prerequisite of the output escaping rule.

**Approved Decision**

`app/helpers/escape_html.php` is an approved prerequisite of INIT-011. It:

- Wraps `htmlspecialchars()` with `ENT_QUOTES` and `UTF-8` encoding
- Is registered in `Bootstrap::loadHelpers()` alongside `env.php`, `config.php`, and `csrf_field.php`
- Is a single function (`escape_html(string $value): string`) guarded by `function_exists()`
- Contains no other logic, no class, no library

Future MIB revisions must add this file to INIT-011 "Files Expected" to prevent this specification gap from recurring.

**Affected Documents**

- MIB v1.0 — INIT-011 "Files Expected": add `app/helpers/escape_html.php`
- DBP v1.0 Ch.8 — Output escaping section: designate `escape_html()` as the canonical escaping function
- TCS — Add `escape_html()` to global helper conventions

**Implementation Impact**

`escape_html()` is available in all view files, layouts, and components. All Sprint 1+ view code that echoes user-derived or database-derived data must call it.

**Migration Required**

No. No pre-existing views output raw variables.

**Risk**

None. The function is a transparent pass-through wrapper.

**Status**

Approved.

---

### REV-017 — Portal Layout Declaration Is a Controller Responsibility

**Background**

`BaseController` was implemented in INIT-008 with `protected string $layout = 'app'`. The `render()` method resolves the layout file as `app/views/layouts/{$this->layout}.php`.

**Finding**

INIT-011 created four portal-specific layout files:

- `app/views/layouts/couple.php`
- `app/views/layouts/admin.php`
- `app/views/layouts/crew.php`
- `app/views/layouts/public.php`

No `app/views/layouts/app.php` was created or listed in the INIT-011 "Files Expected." The default `$layout = 'app'` therefore resolves to a non-existent file. `BaseController::render()` handles this gracefully — falling back to outputting `$content` directly — but the intent of the architecture is that every controller declares its portal explicitly.

**Approved Decision**

The default `$layout = 'app'` is a safe no-layout fallback, not a reference to a real layout file. No generic "app" layout shall be created. Portal specificity is a design requirement — each portal controller is required to declare its layout:

| Portal | Required Declaration |
|--------|---------------------|
| Couple Portal | `$this->layout = 'couple'` |
| Super Admin Portal | `$this->layout = 'admin'` |
| Crew Portal | `$this->layout = 'crew'` |
| Public (Guest) | `$this->layout = 'public'` |

**Affected Documents**

- DBP v1.0 Ch.4 — Document that each portal controller must declare `$layout`; no generic "app" layout exists; the "app" default is an intentional no-layout fallback
- MIB — Each portal module's controller section: note the required `$layout` value
- TCS — Add `$layout` declaration to the controller implementation checklist

**Implementation Impact**

Every Sprint 1+ controller extending `BaseController` must declare `$layout` explicitly. Missing declarations produce unstyled output (no layout wrapping), which is a visible but non-fatal failure.

**Migration Required**

No.

**Risk**

Medium. Forgetting to declare `$layout` in a new controller produces visibly unstyled pages. The risk is mitigated by the graceful fallback (no crash) and the immediate visibility of the error in the browser.

**Status**

Approved.

---

### REV-018 — SESSION_INACTIVITY_TIMEOUT Formalized as a Required Configuration Key

**Background**

The Sprint 0 Execution Plan listed environment keys for session configuration. The `.env.example` key list did not include `SESSION_INACTIVITY_TIMEOUT`.

**Finding**

MIB AUTH-004 specifies *"inactivity timeout (2h)"* as a required session security rule. Omitting this key from configuration would require a hardcoded magic number when `AuthMiddleware` and `CsrfMiddleware` are implemented in Sprint 2. Including it in Sprint 0 closes the specification gap before the implementing sprint.

**Approved Decision**

`SESSION_INACTIVITY_TIMEOUT` is a formally required `.env` key. Its canonical default value is `7200` (seconds = 2 hours), consistent with MIB AUTH-004. Sprint 2 must read this value from `config('session.inactivity_timeout')`.

**Affected Documents**

- MIB v1.0 — Add `SESSION_INACTIVITY_TIMEOUT` to the `.env` key list and to INIT-002 "Files Expected"
- DBP v1.0 Ch.6 — Document `SESSION_INACTIVITY_TIMEOUT` as a required session configuration key

**Implementation Impact**

The value is already present in `config/session.php`. Sprint 2 Auth middleware must reference it through the config helper.

**Migration Required**

No.

**Risk**

None.

**Status**

Approved.

---

### REV-019 — config() Root Resolution Pattern Formalized for Pre-Bootstrap Context

**Background**

`ROOT_PATH` is defined in `public/index.php` (the front controller, INIT-003). The `config()` helper function is in `app/helpers/config.php` (INIT-005). Because INIT-005 precedes INIT-003 in the execution sequence, `ROOT_PATH` is not available when `config.php` is first parsed.

**Finding**

`config()` must locate the `config/` directory without relying on `ROOT_PATH`. The resolution adopted during INIT-005 derives the project root from the helper's own file location:

```
dirname(dirname(dirname(__FILE__)))
```

This resolves relative to `app/helpers/config.php` — three levels up — and correctly identifies the project root. This is the standard PHP pattern for libraries that must function before any bootstrapping has occurred.

This behaviour must be documented to prevent future maintainers from mistakenly replacing it with a `ROOT_PATH` reference, which would cause a fatal constant-not-defined error in pre-bootstrap contexts such as CLI test scripts.

**Approved Decision**

The `__FILE__`-based root resolution in `config()` is the correct and intentional pattern. All helpers in `app/helpers/` that need the project root before Bootstrap has run must use this same pattern. Helpers must not assume `ROOT_PATH` is defined.

**Affected Documents**

- DBP v1.0 Ch.5 — Document `config()` root resolution pattern; note that `ROOT_PATH` is not available during helper load
- TCS — Add to helper implementation guidelines: `app/helpers/` files must not reference `ROOT_PATH`

**Implementation Impact**

Sprint 1+ helpers that require the project root and that may be loaded before Bootstrap must use the `__FILE__`-based pattern.

**Migration Required**

No.

**Risk**

Low. Incorrect replacement of `__FILE__` with `ROOT_PATH` in a future edit would cause a fatal error in CLI validation scripts.

**Status**

Approved.

---

### REV-020 — BaseModel::count() Formalized as a Core Data Access Primitive

**Background**

The Sprint 0 Execution Plan described five `BaseModel` methods: `find()`, `findAll()`, `insert()`, `update()`, `query()`.

**Finding**

Paginated list views require a total row count to calculate page totals. Without `count()` at the base model level, each module model would independently implement equivalent COUNT SQL logic — duplicating a universal operation. `count()` is a single-statement query primitive that belongs to the same responsibility layer as the five documented methods.

**Approved Decision**

`BaseModel::count()` is formalized as a sixth core data access primitive. It is considered part of the canonical base model contract alongside `find`, `findAll`, `insert`, `update`, and `query`.

**Affected Documents**

- MIB v1.0 — INIT-008 "Files Expected": add `count()` to the `BaseModel` method list
- DBP v1.0 Ch.4 — Add `count()` to the BaseModel API documentation

**Implementation Impact**

Sprint 1+ modules may call `$this->count(['workspace_id' => $id])` without adding count logic to individual models.

**Migration Required**

No.

**Risk**

None.

**Status**

Approved.

---

### REV-022 — CLI Validation Test Scaffold Pattern Formalized

**Background**

During validation testing across INIT-006, INIT-007, and INIT-008, PHP CLI test scripts produced `Cannot modify header information — headers already sent` warnings when `echo` output preceded `header()` or `session_start()` calls.

**Finding**

This warning appears exclusively in CLI test contexts. PHP CLI does not buffer output the same way Apache does. In a real web request, the output buffering and request lifecycle prevent this entirely. The warning is a test scaffold artifact, not an application defect.

The pattern adopted in all subsequent validation scripts resolves this by wrapping the Bootstrap initialization in an output buffer:

```
ob_start();
$bootstrap->init();
ob_end_clean();
// echo output is safe from here
```

**Approved Decision**

This is a formalized test methodology rule. All validation scripts for Sprint 1+ must follow the **boot before echo** pattern: `Bootstrap::init()` must be called and its output discarded before any `echo` statement in a CLI test script.

**Affected Documents**

- TCS — Add "CLI test scaffold rule: Bootstrap::init() must precede all echo statements; wrap in ob_start() / ob_end_clean()"
- AI.md — Add to operational rules: validation scripts must boot before producing output

**Implementation Impact**

Sprint 1+ validation scripts must follow this pattern. The pattern is already established in INIT-010 and INIT-011 validation scripts.

**Migration Required**

No.

**Risk**

None. Non-compliance produces a visible PHP warning in CI output only.

**Status**

Approved.

---

### REV-023 — Documentation Authority Hierarchy Formalized

**Background**

Sprint 0 revealed several instances where implementation task prompts conflicted with higher-level architecture documents. In each case, the correct resolution required escalating to the authoritative document rather than following the most recent instruction. No formal priority order existed to guide this process.

**Finding**

Conflicts arose between:

- Initial INIT-011 prompt ("Logging Finalization") vs. Sprint 0 Execution Plan ("View Renderer and Layout System") — REV-015
- INIT-009 prompt listing middleware stubs vs. revised task prompt restricting scope — REV-013
- escape_html() mandated by the escaping rule but absent from all "Files Expected" lists — REV-016

In each case, implementation was stopped and the conflict reported. Resolution required explicit approval. Without a formal authority hierarchy, the resolution path was implicit.

**Approved Decision**

The following documentation authority hierarchy is formally adopted. When any lower-level document conflicts with a higher-level document, the lower-level document must not be followed. Implementation must stop, the conflict must be reported, and approval must be obtained before proceeding.

```
AI.md                    ← Highest authority
    ↓
ADR
    ↓
MIB
    ↓
Sprint Execution Plan
    ↓
Implementation Prompt
    ↓
Implementation           ← Lowest authority
```

**Protocol when a conflict is detected:**

1. Stop. Do not implement.
2. Identify which two documents conflict and at which level.
3. Report the conflict with the exact conflicting text from each document.
4. Wait for explicit approval before proceeding.

**Affected Documents**

- AI.md — Add documentation authority hierarchy and conflict protocol to operational rules
- WORKFLOW.md — Add conflict escalation procedure
- PROJECT.md — Reference the authority hierarchy

**Implementation Impact**

None. This is a documentation governance rule. It formalizes a conflict resolution practice that was already applied throughout Sprint 0.

**Migration Required**

No.

**Risk**

None. The rule reduces risk by preventing implementation that contradicts approved architecture.

**Status**

Approved.

---

## Revision Matrix

| Revision | REV-010 | REV-011 | REV-013 | REV-015 | REV-016 | REV-017 | REV-018 | REV-019 | REV-020 | REV-022 | REV-023 |
|----------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|
| PRD | — | — | — | — | — | — | — | — | — | — | — |
| SAD | — | — | — | — | — | — | — | — | — | — | — |
| DDD | — | — | — | — | — | — | — | — | — | — | — |
| PDD | — | — | — | — | — | — | — | — | — | — | — |
| ADR | — | — | — | — | — | — | — | — | — | — | — |
| DBP | — | ✔ | — | — | ✔ | ✔ | ✔ | ✔ | ✔ | — | — |
| MIB | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | — | ✔ | — | — |
| TCS | — | — | — | — | ✔ | ✔ | — | ✔ | — | ✔ | — |
| AI.md | — | — | — | — | — | — | — | — | — | ✔ | ✔ |
| WORKFLOW.md | — | — | — | — | — | — | — | — | — | — | ✔ |
| PROJECT.md | — | — | — | — | — | — | — | — | — | — | ✔ |
| IMPL_ROADMAP | — | — | — | — | — | — | — | — | — | — | — |
| Sprint 0 Plan | ✔ | ✔ | ✔ | ✔ | — | — | — | — | — | — | — |

---

## Documents Requiring Updates

### PRD

No revisions required. Sprint 0 findings are below the PRD level of abstraction.

### SAD

No revisions required. Sprint 0 findings do not change system architecture at the SAD level.

### DDD

No revisions required. Sprint 0 findings are at the infrastructure layer, below the domain model.

### PDD

No revisions required. Sprint 0 findings do not affect the physical database design.

### ADR

No revisions required. No new decisions that rise to ADR-level significance were made in Sprint 0.

### DBP

Updates required for the following sections:

| Section | Required Update | Revision |
|---------|----------------|---------|
| Ch.4 — BaseController | Document $layout default as a no-layout fallback; document portal override requirement | REV-017 |
| Ch.4 — BaseModel | Add count() to the canonical method list | REV-020 |
| Ch.5 — Bootstrapping | Document __FILE__-based root resolution rule for pre-Bootstrap helpers | REV-019 |
| Ch.6 — Session | Document SESSION_INACTIVITY_TIMEOUT as a required configuration key | REV-018 |
| Ch.7 — Logging | Clarify Logger.php is production-complete after INIT-006; no finalization task | REV-015 |
| Ch.8 — Views | Designate escape_html() as the canonical escaping function; document no generic "app" layout | REV-016, REV-017 |
| Ch.8 — Database Validation | Note INIT-012 is validation-only; no new files when INIT-008 precedes it | REV-011 |

### MIB

Updates required for the following task entries:

| Task | Required Update | Revision |
|------|----------------|---------|
| All | Add explicit Execution Sequence section separate from task ID numbering | REV-010 |
| INIT-002 | Add SESSION_INACTIVITY_TIMEOUT to .env key list | REV-018 |
| INIT-006 | Clarify Logger.php is production-complete, not a skeleton | REV-015 |
| INIT-008 | Add count() to BaseModel method list; add layout override note to BaseController | REV-017, REV-020 |
| INIT-009 | Reduce "Files Expected" to MiddlewarePipeline.php only | REV-013 |
| INIT-011 | Add app/helpers/escape_html.php to "Files Expected" | REV-016 |
| INIT-012 | Change "creates/completes" to "validates"; add INIT-008 as prerequisite; correct position in execution sequence | REV-011 |
| Auth/Role/CSRF/Workspace/Guest/Support Middleware | Add each to the "Files Expected" of its implementing sprint | REV-013 |

### TCS

Updates required:

| Area | Required Update | Revision |
|------|----------------|---------|
| Helper conventions | Designate escape_html() as the canonical output escaping function | REV-016 |
| Helper conventions | Note that app/helpers/ files must not reference ROOT_PATH | REV-019 |
| Controller conventions | Add $layout declaration to the controller implementation checklist | REV-017 |
| Test scaffold conventions | Add CLI boot-before-echo rule: Bootstrap::init() inside ob_start()/ob_end_clean() | REV-022 |

### AI.md

Updates required:

| Section | Required Update | Revision |
|---------|----------------|---------|
| Operational rules | Add documentation authority hierarchy and conflict protocol | REV-023 |
| Operational rules | Add CLI test scaffold rule: Bootstrap::init() must precede all echo statements | REV-022 |

### WORKFLOW.md

Updates required:

| Section | Required Update | Revision |
|---------|----------------|---------|
| Conflict resolution | Add conflict escalation procedure per the authority hierarchy | REV-023 |

### PROJECT.md

Updates required:

| Section | Required Update | Revision |
|---------|----------------|---------|
| Documentation governance | Reference the authority hierarchy established by REV-023 | REV-023 |

### IMPLEMENTATION_ROADMAP.md

No revisions required. Sprint-level roadmap is unaffected.

---

## Sprint 0 Lessons Learned

### 1. Task ID ≠ Execution Order

INIT task numbers are identifiers, not execution sequences. The dependency graph must always be consulted before sequencing tasks. This caused confusion at INIT-012 positioning and must be preemptively clarified in future sprint planning.

### 2. "Finalization" Tasks Require Explicit Scope

When a task is described as "finalization" of a previous task, it risks being a no-op if the previous task was implemented to completion rather than as a skeleton. Sprint 0 demonstrated that INIT-006 (Logger.php) was already complete — a separate finalization task would have produced no deliverable. Future sprint planning must avoid "finalization" tasks unless a concrete file list and acceptance criteria are defined.

### 3. Middleware Belongs in Its Implementing Sprint

Creating middleware stubs before the module they guard exists leads to dead code that references undefined types and will be rewritten entirely. The established pattern is: the pipeline engine in Sprint 0; each concrete middleware class in the sprint that implements its domain logic.

### 4. Functional Rules Must Reference Their Artifacts

The output escaping rule mandated `escape_html()` without specifying the file that provides it. Any specification rule that requires calling a function or using a class must explicitly name the artifact that supplies it under "Files Expected." Rules without artifacts are incomplete specifications.

### 5. Examples Are Not Deliverables

Documentation examples — code snippets, sample configurations, illustrative file structures — must not be interpreted as implementation artifacts. Only the "Files Expected" section of a MIB task defines implementation scope. If an example appears in documentation and is not listed in "Files Expected," it is illustrative only and must not be created without explicit approval.

### 6. Implicit Prerequisites Require Explicit Approval

If documentation requires a helper, utility, or dependency that does not yet exist and is not listed in the current task's "Files Expected," implementation must stop. The gap must be reported and explicit approval obtained before the prerequisite is created. Silent introduction of implementation artifacts is not permitted.

### 7. Portal Layout Is a Controller Declaration

`$layout = 'app'` with no corresponding layout file is a silent failure mode — no crash, but unstyled output. The architecture requires each portal controller to explicitly declare its layout. Future sprint conventions should enforce this at the code review stage.

### 8. CLI Test Scaffolding Pattern Is Now Established

The pattern of `ob_start() → Bootstrap::init() → ob_end_clean()` before any `echo` statement is the official CLI test scaffold for this project. All future validation scripts must follow it.

---

## Approval Workflow

This document is produced by the AI implementation agent based on evidence gathered during Sprint 0 implementation.

Before any official documentation is updated:

1. **Human review**: Each revision in this document must be reviewed by the project owner.
2. **Individual approval or rejection**: Each revision is accepted or rejected individually. Acceptance does not imply immediate documentation update.
3. **Documentation update**: Approved revisions are incorporated into the affected documents in a dedicated documentation update task.
4. **This document becomes**: A permanent historical record of Sprint 0 architectural findings.

No source code changes are implied by this document. All Sprint 0 source code remains as implemented.

---

## Final Statement

Sprint 0 establishes the official framework baseline for Inveetaire.

Every layer of the application — environment loading, configuration, bootstrapping, error handling, logging, routing, request lifecycle, database connectivity, middleware pipeline, session management, CSRF protection, and view rendering — has been implemented, validated, and confirmed against the approved architecture documents.

Future development shall build upon this baseline. No module, sprint, or feature may alter the framework foundation established here without first documenting the change through a subsequent Design Revision Pack, obtaining approval, and updating the affected architecture documents before modifying any code.

The baseline is stable. Sprint 1 may proceed.

---

*Document produced: 2026-06-30*
*Revision count: 11 (REV-010, REV-011, REV-013, REV-015 through REV-020, REV-022, REV-023)*
*Source: Sprint 0 implementation memory — INIT-001 through INIT-012*