docs(25-07): complete agent-generated file support and placeholder tracking plan — SUMMARY, STATE, ROADMAP updated

2026-04-02 00:14:08 +00:00 · 2026-04-02 00:14:08 +00:00 · f04badf9f4
commit f04badf9f4
parent 7ab49d9824
3 changed files with 124 additions and 11 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -14,7 +14,7 @@
 - [x] **Phase 22: Agent Streaming** — Real-time streaming via SSE/WebSocket, agent selector, agent identity on messages, stop/edit/regenerate, slash commands and @mentions (completed 2026-04-01)
 - [x] **Phase 23: Brainstormer Flow** — Brainstormer agent persona, structured questioning flow, spec generation, PM handoff, task creation from chat, agent status updates in chat (completed 2026-04-01)
 - [x] **Phase 24: Search, History & Branching** — Full-text search across all conversations, export, conversation branching, message bookmarks (completed 2026-04-01)
- [ ] **Phase 25: File System** — Local file storage with dual scoping, libSQL tracking, inline preview, download, agent-generated files, git versioning, placeholder tracking (gap closure in progress)
+- [x] **Phase 25: File System** — Local file storage with dual scoping, libSQL tracking, inline preview, download, agent-generated files, git versioning, placeholder tracking (gap closure in progress) (completed 2026-04-02)
 - [ ] **Phase 26: PWA & Performance** — Service worker, Web App Manifest, responsive mobile layout, push notifications, install prompt, performance targets

 ---
@ -116,7 +116,7 @@ Plans:
  5. When an agent generates a placeholder asset, `PLACEHOLDERS.md` is updated in the project directory; when the placeholder is replaced, the DB records the replacement chain and the manifest reflects the change
  6. A file uploaded in a conversation linked to a project lives in `files/projects/<slug>/`; a file from an unlinked conversation lives in `files/chat/<conversation-id>/`; the user can promote a chat file to project scope
  7. Voice input is available when local AI is enabled: user can hold the record button, speak, see a transcription preview, and confirm to send
-**Plans:** 8/9 plans executed
+**Plans:** 9/9 plans complete

 Plans:
 - [x] 25-00-PLAN.md — DB schema (chat_files + chat_file_references), shared types/validators, test stubs
@ -126,7 +126,7 @@ Plans:
 - [x] 25-04-PLAN.md — Gap: Code syntax-highlighted preview (FILE-06) + admin claims (FILE-07, FILE-13)
 - [x] 25-05-PLAN.md — Gap: File scope promotion API + UI (FILE-12)
 - [x] 25-06-PLAN.md — Gap: Git integration for file operations + version history (FILE-09, FILE-10)
- [ ] 25-07-PLAN.md — Gap: Agent-generated files + placeholder tracking (FILE-08, FILE-11)
+- [x] 25-07-PLAN.md — Gap: Agent-generated files + placeholder tracking (FILE-08, FILE-11)
 - [x] 25-08-PLAN.md — Gap: Voice input via Whisper (INPUT-04) + admin claims (INPUT-02, INPUT-03)

 **UI hint**: yes
@ -227,5 +227,5 @@ All 65 v1 requirements are mapped to exactly one phase. No orphans.
 | 22. Agent Streaming | v1.3 | 6/6 | Complete    | 2026-04-01 |
 | 23. Brainstormer Flow | v1.3 | 4/4 | Complete    | 2026-04-01 |
 | 24. Search, History & Branching | v1.3 | 4/4 | Complete    | 2026-04-01 |
-| 25. File System | v1.3 | 8/9 | In Progress|  |
+| 25. File System | v1.3 | 9/9 | Complete   | 2026-04-02 |
 | 26. PWA & Performance | v1.3 | 0/? | Not started | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.3
 milestone_name: milestone
 status: executing
-stopped_at: Completed 25-file-system-25-06-PLAN.md
-last_updated: "2026-04-02T00:06:07.957Z"
+stopped_at: Completed 25-file-system-25-07-PLAN.md
+last_updated: "2026-04-02T00:13:52.105Z"
 last_activity: 2026-04-02
 progress:
  total_phases: 6
-  completed_phases: 4
+  completed_phases: 5
  total_plans: 30
-  completed_plans: 29
+  completed_plans: 30
  percent: 100
 ---

@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-03-30)
 ## Current Position

 Phase: 25 (file-system) — EXECUTING
-Plan: 4 of 9
+Plan: 5 of 9
 Status: Ready to execute
 Last activity: 2026-04-02

@ -85,6 +85,7 @@ Progress: [██████████] 100%
 | Phase 25-file-system P08 | 8 | 2 tasks | 5 files |
 | Phase 25-file-system P04 | 5min | 2 tasks | 5 files |
 | Phase 25-file-system P06 | 5 | 2 tasks | 5 files |
+| Phase 25-file-system P07 | 10 | 2 tasks | 6 files |

 ## Accumulated Context

@ -157,6 +158,9 @@ Recent decisions affecting current work:
 - [Phase 25-file-system]: Used execFile (not exec) for git commands in gitFileService — array-based args prevent shell injection
 - [Phase 25-file-system]: Git commit is fire-and-forget after upload — response not blocked by git operation
 - [Phase 25-file-system]: History route placed before /content route to avoid Express path ambiguity on /files/:fileId/*
+- [Phase 25-file-system]: placeholderService reads/writes PLACEHOLDERS.md using regex row parser to avoid markdown deps
+- [Phase 25-file-system]: addEntry is fire-and-forget — response not blocked by placeholder manifest I/O
+- [Phase 25-file-system]: resolveDefaultStorageDir() used for projectDir in placeholder service — consistent with git-file-service pattern

 ### Pending Todos

@ -169,6 +173,6 @@ None yet.

 ## Session Continuity

-Last session: 2026-04-02T00:06:07.954Z
-Stopped at: Completed 25-file-system-25-06-PLAN.md
+Last session: 2026-04-02T00:13:52.102Z
+Stopped at: Completed 25-file-system-25-07-PLAN.md
 Resume file: None
--- a/.planning/phases/25-file-system/25-07-SUMMARY.md
+++ b/.planning/phases/25-file-system/25-07-SUMMARY.md
@ -0,0 +1,109 @@
+---
+phase: 25-file-system
+plan: 07
+subsystem: api
+tags: [placeholder, agent-generated, manifest, markdown, chat-files]
+
+requires:
+  - phase: 25-01
+    provides: chatFileService with create/getById/createReference methods
+  - phase: 25-06
+    provides: git-file-service with storageDir pattern (on separate worktree; storageDir import added here)
+
+provides:
+  - placeholderService with addEntry/replaceEntry/listEntries managing PLACEHOLDERS.md
+  - chatFileService.markAsPlaceholder method
+  - POST /files/:fileId/replace endpoint for placeholder replacement
+  - Agent-generated file tracking in PLACEHOLDERS.md manifest
+
+affects: [25-06, future-agent-file-generation]
+
+tech-stack:
+  added: []
+  patterns:
+    - placeholderService reads/writes PLACEHOLDERS.md markdown tables
+    - fire-and-forget phSvc.addEntry() on upload (non-blocking)
+    - replace endpoint updates manifest + creates reference chain atomically
+
+key-files:
+  created:
+    - server/src/services/placeholder-service.ts
+  modified:
+    - server/src/services/chat-files.ts
+    - server/src/routes/chat-files.ts
+    - packages/shared/src/types/chat.ts
+    - packages/shared/src/index.ts
+    - .planning/REQUIREMENTS.md
+
+key-decisions:
+  - "placeholderService reads/writes PLACEHOLDERS.md using regex row parser to avoid markdown deps"
+  - "addEntry is fire-and-forget (.catch(() => {})) — response not blocked by file I/O"
+  - "replaceEntry is awaited in /replace endpoint — manifest must be consistent before response"
+  - "resolveDefaultStorageDir() used for projectDir path — consistent with git-file-service pattern"
+
+patterns-established:
+  - "Placeholder manifest: Active Placeholders and Replaced markdown tables in PLACEHOLDERS.md per project dir"
+  - "Replace endpoint: phSvc.replaceEntry + fileSvc.createReference for atomically updating both manifest and DB"
+
+requirements-completed: [FILE-08, FILE-11]
+
+duration: 10min
+completed: 2026-04-02
+---
+
+# Phase 25 Plan 07: Agent-Generated File Support and Placeholder Tracking Summary
+
+**PLACEHOLDERS.md manifest service with addEntry/replaceEntry and POST /files/:fileId/replace endpoint wiring agent-generated uploads to per-project markdown manifests**
+
+## Performance
+
+- **Duration:** ~10 min
+- **Started:** 2026-04-02T00:09:00Z
+- **Completed:** 2026-04-02T00:12:49Z
+- **Tasks:** 2
+- **Files modified:** 5
+
+## Accomplishments
+- Created `placeholder-service.ts` with full PLACEHOLDERS.md markdown table management (addEntry, replaceEntry, listEntries)
+- Added `markAsPlaceholder` method to `chatFileService` for DB-level placeholder categorization
+- Wired agent_generated + project-scoped uploads to automatically update PLACEHOLDERS.md
+- Added `POST /files/:fileId/replace` endpoint that updates manifest and creates DB reference chain
+- Marked FILE-08 and FILE-11 Complete in REQUIREMENTS.md
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create placeholderService and add markAsPlaceholder method** - `0a80659c` (feat)
+2. **Task 2: Add placeholder and agent-generated file routes** - `2a4037ca` (feat)
+
+## Files Created/Modified
+- `server/src/services/placeholder-service.ts` - PLACEHOLDERS.md manifest management service (161 lines)
+- `server/src/services/chat-files.ts` - Added markAsPlaceholder method
+- `server/src/routes/chat-files.ts` - Added phSvc import, agent_generated tracking, /replace endpoint
+- `packages/shared/src/types/chat.ts` - Added ChatPlaceholderEntry interface
+- `packages/shared/src/index.ts` - Exported ChatPlaceholderEntry
+- `.planning/REQUIREMENTS.md` - Marked FILE-08 and FILE-11 Complete
+
+## Decisions Made
+- Used regex row parser (`/^\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|$/`) to parse markdown tables — no external markdown deps needed
+- `addEntry` is fire-and-forget (non-blocking) to avoid blocking upload response
+- `replaceEntry` is awaited in the replace endpoint for manifest consistency before response
+- Used `resolveDefaultStorageDir()` for project dir base path, consistent with 25-06 storageDir pattern
+- `git-file-service.ts` not present on this branch (in 25-06 worktree); storageDir import added here for placeholder path only
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+- `git-file-service.ts` not present on current branch (it's in the 25-06 worktree). Per the important_context note, proceeded with placeholder-service implementation and imported `resolveDefaultStorageDir` directly for the project path computation. No blocking impact.
+
+## Next Phase Readiness
+- PLACEHOLDERS.md manifest management complete; any agent that uploads with source=agent_generated and projectId will auto-track
+- Replace endpoint ready for agent workflows that upgrade placeholder assets to final outputs
+- FILE-08 and FILE-11 marked complete
+
+---
+*Phase: 25-file-system*
+*Completed: 2026-04-02*