Kilo Pages (Isolated MVC) + Pre-Read Index

[Phosphate5429]

Summary

Add a framework mode to Kilo where each page or feature is an isolated micro MVC module with integrated documentation.
Before any code generation or edit, Kilo performs a full pre-read scan of the project (files, docs, Git history, commits, diffs, etc.) to build a context index that guides the AI while enforcing a single-module write scope.

---

Goals

• Simplicity & Safety for AI workflows — cross-read, single-write.
• Integrated documentation per module, rendered directly inside Kilo.
• Full historical awareness — AI understands architecture, conventions, and past decisions.
• Atomic rollback — one commit per module, easily revertible.

---

Micro-Module Structure

app/pages/
  Home/
    Home.model.php
    Home.controller.php
    Home.view.php
    Home.routes.php
    README.md            # local doc (contract + rules)
    ADR.md               # architectural decisions (optional)
    assets/
    Home.test.php        # optional local tests

README.md (integrated local doc)

• Purpose — short description
• Inputs/Outputs — params, DTOs
• Dependencies — services, helpers
• Rules — conventions, pitfalls
• Write boundaries — allowed files for editing
• QA checklist — manual or automated tests

Kilo renders this documentation directly in the sidebar when the module is selected.

---

Pre-Read Index (before writing)

When a repository is opened (or a module selected), Kilo builds a Pre-Read Index that gathers context from:

1. Code & Doc parsing

   • Scans app/pages/**
   • Extracts READMEs and ADRs
   • Detects routes, controllers, models, and assets

2. Git Analysis

   • git log -- <module> → last commits, messages, authors
   • git blame → most frequently modified lines
   • git diff main...HEAD → current work in progress
   • (optional) tags, releases, related branches

3. Dependency Mapping

   • Inter-module imports and service usage
   • Entry points (HTTP routes, CLI, background jobs)

4. Risk & Impact Scoring

   • Edit frequency, touched files, and hot zones
   • Critical files flagged as read-only
   • Suggested tests for verification

The Index is displayed in Kilo (under a “Context” tab) and is also provided as condensed context input for the AI.

---

Typical Flow in Kilo

1. Open repo → Kilo automatically runs Pre-Read Index (cached).
2. Select a module → Kilo displays its README and context index.
3. Lock edit scope → write access limited to app/pages/<Module>.
4. AI generates change plan → user reviews & approves.
5. Patch applied → atomic commit feat(page): <Module>.
6. Quick QA → local tests + checklist from README.
7. Rollback button → revert commit instantly.

---

Safety Features

• Edits outside the module directory → blocked (with reason + suggestion).
• Attempts to modify “critical” files flagged by the Index → require confirmation.
• Always show diff preview limited to the module before commit.
• Visible Git context: last author, message, diff summary.

---

CLI Integration

kilo make:page Home
kilo index:build         # rebuild global Pre-Read Index
kilo index:page Home     # build index for specific module
kilo lock Home / unlock Home
kilo test Home
kilo docs Home           # open integrated documentation

Git Hooks

• pre-commit → verifies whitelist + runs local tests/lint
• commit-msg → enforces commit naming convention feat/fix(page): <Name>

---

VS Code UI (Kilo extension)

• Pages Panel — lists modules, lock status, recent commits
• Doc Panel — renders module README/ADR (Markdown)
• Context Panel — shows Pre-Read Index (routes, deps, authors, risks)
• Diff Panel — displays current patch (scoped to module), with Rollback button

---

MVP — Acceptance Criteria

1. kilo make:page Foo generates a working scaffold and route.
2. On repo open, Kilo shows a Context Index (files, routes, last 5 commits).
3. Selecting a module displays integrated docs, applies a lock, and blocks writes outside the scope.
4. Each change produces one atomic commit with rollback available.
5. kilo index:page Foo lists routes, detected dependencies, and recent Git activity.

---

Implementation Notes

• Parser → glob scan using naming convention <Name>.(model|controller|view).php
• Git Integration → run native git commands (log, show, blame, diff) and summarize as JSON
• Index Cache → .kilo/index.json (with HEAD hash + timestamps)
• Write Whitelist → enforced in both Kilo extension and backend (rejects out-of-scope edits)
• Markdown Renderer → for displaying README/ADR
• Risk Score → simple formula: score = edits_30d + files_touched + blame_hotspots

---

Migration Tool

kilo migrate:to-pages

• Detects existing routes/controllers
• Creates app/pages/<Name>/ folders
• Moves or duplicates relevant M/C/V files
• Generates a minimal README contract

---

Value

• The AI reads everything first (code, docs, Git history) before writing.
• Developers retain traceability, safety, and control.
• Projects stay modular, maintainable, and AI-friendly.