docs(01-01): complete project scaffolding plan

- Create 01-01-SUMMARY.md documenting plan execution
- Update STATE.md with current position and velocity metrics
- Update ROADMAP.md progress table

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.planning/ROADMAP.md

@@ -68,7 +68,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 1. Foundation | 0/TBD | Not started | - |
+| 1. Foundation | 1/TBD | In progress | - |
 | 2. Bot Core | 0/TBD | Not started | - |
 | 3. Project CRUD | 0/TBD | Not started | - |
 | 4. Single Model Q&A | 0/TBD | Not started | - |

.planning/STATE.md

@@ -10,28 +10,28 @@ See: .planning/PROJECT.md (updated 2026-01-16)
 ## Current Position
 
 Phase: 1 of 6 (Foundation)
-Plan: Not started
+Plan: 1 of TBD complete
-Status: Ready to plan
+Status: In progress
-Last activity: 2026-01-16 — Project initialized
+Last activity: 2026-01-16 — Completed 01-01-PLAN.md (project scaffolding)
 
-Progress: ░░░░░░░░░░ 0%
+Progress: █░░░░░░░░░ ~10%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 0
+- Total plans completed: 1
-- Average duration: —
+- Average duration: 8 min
-- Total execution time: 0 hours
+- Total execution time: 0.13 hours
 
 **By Phase:**
 
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
-| — | — | — | — |
+| 01-foundation | 1 | 8 min | 8 min |
 
 **Recent Trend:**
-- Last 5 plans: —
+- Last 5 plans: 01-01 (8 min)
-- Trend: —
+- Trend: Starting
 
 ## Accumulated Context
 
@@ -40,7 +40,8 @@ Progress: ░░░░░░░░░░ 0%
 Decisions are logged in PROJECT.md Key Decisions table.
 Recent decisions affecting current work:
 
-(None yet)
+- **01-01:** hatchling as build backend with explicit src layout config
+- **01-01:** ruff-pre-commit v0.14.13 with --fix for auto-corrections
 
 ### Deferred Issues
 

.planning/phases/01-foundation/01-01-SUMMARY.md

@@ -0,0 +1,119 @@
+---
+phase: 01-foundation
+plan: 01
+subsystem: infra
+tags: [python, ruff, pre-commit, hatchling, pytest]
+
+# Dependency graph
+requires: []
+provides:
+  - Python project structure with src layout
+  - pyproject.toml with hatchling build backend
+  - ruff linting and formatting configuration
+  - pre-commit hooks for code quality
+  - pytest configuration with async support
+affects: [02-bot-core, all-future-phases]
+
+# Tech tracking
+tech-stack:
+  added: [python-telegram-bot, sqlalchemy, httpx, aiosqlite, pytest, pytest-cov, pytest-asyncio, ruff, pre-commit, hatchling]
+  patterns: [src-layout, editable-install]
+
+key-files:
+  created:
+    - pyproject.toml
+    - .pre-commit-config.yaml
+    - src/moai/__init__.py
+    - src/moai/bot/__init__.py
+    - src/moai/bot/handlers/__init__.py
+    - src/moai/core/__init__.py
+    - tests/__init__.py
+  modified: []
+
+key-decisions:
+  - "hatchling as build backend (modern, works well with uv/pip)"
+  - "src layout with tool.hatch.build.targets.wheel.packages configuration"
+  - "ruff-pre-commit v0.14.13 with --fix flag for auto-corrections"
+  - "pre-commit-hooks v5.0.0 for standard file hygiene"
+
+patterns-established:
+  - "src layout: all source code under src/moai/"
+  - "Module docstrings: required on all __init__.py files"
+  - "Version in __init__.py: moai.__version__ for programmatic access"
+
+issues-created: []
+
+# Metrics
+duration: 8min
+completed: 2026-01-16
+---
+
+# Phase 1, Plan 1: Project Scaffolding Summary
+
+**Python project scaffolding with pyproject.toml (hatchling), ruff linting, pre-commit hooks, and src layout structure**
+
+## Performance
+
+- **Duration:** 8 min
+- **Started:** 2026-01-16T15:00:00Z
+- **Completed:** 2026-01-16T15:08:00Z
+- **Tasks:** 3
+- **Files created:** 7
+
+## Accomplishments
+- Created pyproject.toml with all dependencies and tool configurations
+- Configured pre-commit with ruff linting/formatting and standard hygiene hooks
+- Established src layout package structure matching SPEC.md architecture
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create pyproject.toml** - `39b1781` (build)
+2. **Task 2: Create pre-commit configuration** - `5856e6b` (chore)
+3. **Task 3: Create src layout and package structure** - `44e2322` (feat)
+
+**Plan metadata:** (pending)
+
+## Files Created/Modified
+- `pyproject.toml` - Project metadata, dependencies, ruff/pytest config
+- `.pre-commit-config.yaml` - Pre-commit hooks configuration
+- `src/moai/__init__.py` - Package root with __version__
+- `src/moai/bot/__init__.py` - Bot subpackage marker
+- `src/moai/bot/handlers/__init__.py` - Handlers subpackage marker
+- `src/moai/core/__init__.py` - Core subpackage marker
+- `tests/__init__.py` - Test package marker
+
+## Decisions Made
+- Used hatchling with explicit `packages = ["src/moai"]` for src layout (required for editable install)
+- Selected ruff-pre-commit v0.14.13 (latest stable as of 2026-01-16)
+- Used pre-commit-hooks v5.0.0 for standard hooks
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Added hatch build configuration for src layout**
+- **Found during:** Task 1 (pyproject.toml creation)
+- **Issue:** Hatchling couldn't find package without explicit src layout config
+- **Fix:** Added `[tool.hatch.build.targets.wheel] packages = ["src/moai"]`
+- **Files modified:** pyproject.toml
+- **Verification:** pip install -e ".[dev]" succeeds
+- **Committed in:** 39b1781 (Task 1 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (blocking issue), 0 deferred
+**Impact on plan:** Auto-fix was necessary for hatchling to work with src layout. No scope creep.
+
+## Issues Encountered
+None - all tasks completed successfully after the hatchling configuration fix.
+
+## Next Phase Readiness
+- Project scaffolding complete, ready for Phase 1 Plan 2 (database models)
+- All tooling in place: ruff, pre-commit, pytest
+- Package importable and version accessible
+
+---
+*Phase: 01-foundation*
+*Completed: 2026-01-16*