feat: finalize AI logging framework and workflow

- align instructions, workflow rules, and task template with three-level logging
- extend ai-task generation to support execution-log requirements
- update worklog, prompt log, and execution log for the finalized framework
- validate the framework with generator and project quality checks

AGENT.md

@@ -0,0 +1,260 @@
+# AGENT.md
+
+AI Agent Development Guide
+
+This file defines the operational rules that AI agents must follow when working in this repository.
+
+The goal is to ensure:
+- reproducible AI-assisted development
+- traceable decisions
+- consistent repository history
+- safe automated contributions
+
+This document complements:
+- `instructions-agent.md`
+- `docs/ai-worklog.md`
+- `docs/ai-prompts.md`
+
+---
+
+# Core Principles
+
+Agents must prioritize:
+
+1. Deterministic changes
+2. Minimal scope modifications
+3. Explicit logging of work
+4. Repository stability
+
+Agents must never:
+
+- fabricate repository state
+- invent files that do not exist
+- modify unrelated parts of the project
+- skip validation steps
+
+---
+
+# Development Workflow
+
+Agents operate using two primary task types:
+
+## PLAN
+
+Used to:
+- investigate problems
+- inspect repository state
+- propose architecture changes
+
+PLAN tasks must:
+- analyze the current implementation
+- identify the root cause
+- propose minimal changes
+
+PLAN tasks **must not modify code**.
+
+---
+
+## BUILD
+
+Used to:
+- implement changes
+- update code
+- add tests
+- update documentation
+
+BUILD tasks may:
+- modify source files
+- update tests
+- update documentation
+
+BUILD tasks must:
+- remain minimal in scope
+- preserve existing behavior unless explicitly changed
+
+---
+
+# Validation Requirements
+
+All BUILD tasks must run:
+
+```
+make fix
+make quality
+```
+
+These commands must pass before changes are considered valid.
+
+---
+
+# Logging System
+
+All significant AI actions must be recorded.
+
+Two log files are used:
+
+```
+docs/ai-worklog.md
+docs/ai-prompts.md
+```
+
+---
+
+# Worklog Entries
+
+Executed work must be recorded in:
+
+```
+docs/ai-worklog.md
+```
+
+Each entry must follow the standard format defined in `instructions-agent.md`.
+
+Mandatory fields:
+
+- Date (YYYY-MM-DD HH:MM)
+- Task ID
+- Agent
+- Task
+- Objective
+- Scope
+- Files Modified / Files Inspected
+- Key Decisions / Proposed Changes
+- Validation
+- Result
+- Open Issues
+
+---
+
+# Prompt Log
+
+Prompts that trigger significant work must be recorded in:
+
+```
+docs/ai-prompts.md
+```
+
+Each prompt entry must include:
+
+- Date
+- Task ID
+- Agent
+- Task
+- Scope
+- Prompt Summary
+- Result Summary
+
+Chain-of-thought reasoning must **never be stored**.
+
+---
+
+# Task IDs
+
+All tasks must include a unique identifier.
+
+Format:
+
+```
+BUILD-YYYYMMDD-XXX
+PLAN-YYYYMMDD-XXX
+```
+
+Examples:
+
+```
+BUILD-20260315-001
+PLAN-20260316-002
+```
+
+This allows prompts and worklog entries to be correlated.
+
+---
+
+# Git Rules
+
+Agents must follow these repository rules.
+
+Agents must **not commit or push** unless explicitly requested.
+
+When committing:
+
+Use structured commit messages.
+
+Example:
+
+```
+feat: improve terminal navigation behavior
+
+- refine tree navigation
+- improve scrolling continuity
+- update AI logs
+```
+
+Documentation-only updates should use:
+
+```
+docs:
+```
+
+---
+
+# Code Modification Rules
+
+Agents should prefer:
+
+- small targeted patches
+- isolated logic changes
+- preserving existing abstractions
+
+Agents should avoid:
+
+- rewriting entire modules
+- introducing unnecessary dependencies
+- altering unrelated code paths
+
+---
+
+# UI Changes
+
+When modifying UI behavior:
+
+- keep navigation predictable
+- preserve keyboard ergonomics
+- ensure selections remain visible
+- maintain compatibility with history mode
+
+---
+
+# Testing Rules
+
+Whenever logic changes:
+
+- update existing tests
+- add focused tests when appropriate
+
+Tests should validate behavior, not implementation details.
+
+---
+
+# Scope Discipline
+
+Agents must strictly respect scope defined in prompts.
+
+If additional changes appear necessary:
+
+Agents must propose them in a PLAN task before implementing.
+
+---
+
+# Repository Safety
+
+Agents must not:
+
+- delete important files
+- alter project configuration without justification
+- introduce breaking changes without explicit instruction
+
+---
+
+# End of Document
+---

AGENT_WORKFLOW.md

@@ -0,0 +1,298 @@
+# AGENT_WORKFLOW.md
+
+AI Agent Operational Workflow
+
+This document defines the deterministic workflow that AI agents must follow when performing work in this repository.
+
+The workflow ensures:
+
+- predictable development cycles
+- traceable decisions
+- minimal risk of unintended changes
+- consistent logging of AI actions
+
+This file complements:
+
+- `AGENT.md`
+- `instructions-agent.md`
+- `docs/ai-worklog.md`
+- `docs/ai-prompts.md`
+- `docs/ai-execution-log.md`
+
+---
+
+# Standard Workflow
+
+Every AI task must follow this sequence:
+
+PLAN → REVIEW → BUILD → VALIDATE → LOG
+
+---
+
+# Execution Order (Strict)
+
+The following operational order must be respected when executing any BUILD task.
+
+1. Implement changes (BUILD)
+2. Run validation
+   make fix
+   make quality
+3. Update AI logs
+   - docs/ai-execution-log.md
+   - docs/ai-prompts.md
+   - docs/ai-worklog.md
+4. Stage all modified files including logs
+5. Create commit
+6. Push only if explicitly requested
+
+Important rule:
+Logs must always be written **before creating a commit**. If log files are modified after a commit, the task is considered incomplete and must be corrected.
+
+---
+
+This sequence must not be skipped.
+
+---
+
+# 1. PLAN
+
+Goal:
+Understand the problem and determine the minimal solution.
+
+Actions:
+
+- inspect repository state
+- read relevant source files
+- analyze existing architecture
+- identify root cause of the problem
+- propose a minimal change
+
+Rules:
+
+- PLAN must **not modify code**
+- PLAN must **not change files**
+- PLAN must only produce analysis and a proposal
+
+Output should include:
+
+- diagnosis summary
+- proposed changes
+- expected file scope
+
+---
+
+# 2. REVIEW
+
+Goal:
+Validate the plan before implementing it.
+
+Actions:
+
+- confirm the proposed scope is minimal
+- ensure no unrelated components are affected
+- verify the change aligns with project architecture
+
+Rules:
+
+- If the scope expands unexpectedly, return to PLAN.
+
+---
+
+# 3. BUILD
+
+Goal:
+Implement the approved change.
+
+Actions:
+
+- modify only the files defined in scope
+- preserve existing architecture
+- avoid unnecessary refactors
+- maintain compatibility with existing behavior
+
+BUILD tasks may modify:
+
+- source files
+- tests
+- documentation
+
+BUILD tasks must remain minimal and targeted.
+
+---
+
+# 4. VALIDATE
+
+Goal:
+Ensure the repository remains stable.
+
+Agents must run:
+
+```
+make fix
+make quality
+```
+
+Validation must pass before changes are considered complete.
+
+---
+
+# 5. LOG
+
+Goal:
+Record the AI activity for traceability.
+
+Three log files must be updated.
+
+### Work Log
+
+```
+docs/ai-worklog.md
+```
+
+Record:
+
+- AI BUILD ENTRY
+- or AI PLAN ENTRY
+
+Including:
+
+- Date (YYYY-MM-DD HH:MM)
+- Task ID
+- Agent
+- Task
+- Objective
+- Scope
+- Files Modified / Files Inspected
+- Key Decisions / Proposed Changes
+- Validation
+- Result
+- Open Issues
+
+### Prompt Log
+
+```
+docs/ai-prompts.md
+```
+
+Record:
+
+- Date (YYYY-MM-DD HH:MM)
+- Task ID
+- Agent
+- Task
+- prompt summary
+- scope
+- result summary
+
+Do not store chain-of-thought reasoning.
+
+### Execution Log
+
+```
+docs/ai-execution-log.md
+```
+
+Record the full visible execution trace including:
+
+- Date (YYYY-MM-DD HH:MM)
+- Task ID
+- Agent
+- Task Type
+- Full prompt text
+- Agent todos
+- Execution report
+
+The execution log preserves the complete operational record of the AI session.
+
+---
+
+# Task ID Coordination
+
+Every PLAN or BUILD must generate a unique Task ID.
+
+Format:
+
+```
+PLAN-YYYYMMDD-XXX
+BUILD-YYYYMMDD-XXX
+```
+
+Example:
+
+```
+PLAN-20260316-001
+BUILD-20260316-002
+```
+
+The same Task ID must appear in:
+
+- ai-execution-log.md
+- ai-prompts.md
+- ai-worklog.md
+
+---
+
+# Commit Workflow
+
+Agents must **not commit or push automatically** unless explicitly instructed.
+
+Before creating a commit the agent must ensure:
+
+- validation has passed
+- AI logs have been written
+- docs/ai-execution-log.md, docs/ai-worklog.md and docs/ai-prompts.md are staged
+
+Commits that omit required AI log entries violate the repository workflow rules.
+
+When commits are requested:
+
+1. Validate repository state
+2. Stage modified files
+3. Use structured commit messages
+
+Example:
+
+```
+feat: improve terminal navigation
+
+- refine tree navigation
+- improve scrolling
+- update AI logs
+```
+
+Documentation-only updates should use:
+
+```
+docs:
+```
+
+---
+
+# Failure Handling
+
+If validation fails:
+
+Agents must:
+
+1. stop the BUILD process
+2. report the error
+3. propose a fix
+
+Agents must **not silently bypass failing checks**.
+
+---
+
+# Scope Control
+
+Agents must strictly respect the defined scope.
+
+If additional changes appear necessary:
+
+- return to PLAN
+- propose a new change
+
+Do not expand scope during BUILD.
+
+---
+
+# End of Document

AI_TASK_TEMPLATE.md

@@ -0,0 +1,179 @@
+# AI Task Template
+
+Reusable prompt template for launching tasks with AI agents.
+
+This template enforces the repository workflow defined in:
+
+- AGENT.md
+- AGENT_WORKFLOW.md
+- instructions-agent.md
+
+It ensures every task follows the deterministic sequence:
+
+PLAN → REVIEW → BUILD → VALIDATE → LOG
+
+---
+
+# Basic Task Structure
+
+Use the following structure when requesting work from an AI agent.
+
+```
+Task Type:
+PLAN | BUILD
+
+Task ID:
+PLAN-YYYYMMDD-XXX | BUILD-YYYYMMDD-XXX
+
+Date:
+YYYY-MM-DD HH:MM
+
+Objective:
+Short description of the goal.
+
+Context:
+Relevant background about the current repository state.
+
+Scope:
+List of files or directories the agent may modify or inspect.
+
+Requirements:
+Detailed description of the behavior that must be implemented or analyzed.
+
+Constraints:
+Things the agent must NOT change or must preserve.
+
+Testing:
+Describe expected tests or validations.
+
+Validation:
+The agent must run:
+
+make fix
+make quality
+
+Logging requirements:
+- Append an entry to docs/ai-worklog.md
+- Append an entry to docs/ai-prompts.md
+- Append an entry to docs/ai-execution-log.md
+- Include Date, Task ID, Agent, Scope, Result
+
+Execution Logging requirements:
+- Append an entry to docs/ai-execution-log.md
+- Include:
+  - full prompt
+  - agent todos
+  - final execution report
+- Use the standard execution log format defined in docs/ai-execution-log.md
+
+Git requirements:
+- Do NOT commit or push unless explicitly requested.
+
+Expected Report:
+The agent must summarize:
+- files changed
+- behavior changes
+- validation results
+```
+
+---
+
+# Example BUILD Task
+
+```
+Task Type:
+BUILD
+
+Task ID:
+BUILD-YYYYMMDD-XXX
+
+Date:
+YYYY-MM-DD HH:MM
+
+Objective:
+Improve vertical scrolling behavior in the terminal UI.
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
+Requirements:
+Ensure the selected entry remains visible when navigating through long directory lists.
+
+Constraints:
+Do not modify navigator logic.
+
+Testing:
+Add helper tests if necessary.
+
+Validation:
+make fix
+make quality
+
+Logging requirements:
+- Update `docs/ai-worklog.md` and `docs/ai-prompts.md` using the standard log format.
+
+Execution Logging requirements:
+- Update docs/ai-execution-log.md with:
+  - full prompt
+  - agent todos
+  - final execution report
+
+Git requirements:
+- Do NOT commit or push unless explicitly requested.
+```
+
+---
+
+# Example PLAN Task
+
+```
+Task Type:
+PLAN
+
+Task ID:
+PLAN-YYYYMMDD-XXX
+
+Date:
+YYYY-MM-DD HH:MM
+
+Objective:
+Investigate inconsistent navigation behavior.
+
+Scope:
+- src/app/ui.py
+- src/app/navigator.py
+
+Requirements:
+Analyze the current navigation flow and propose a minimal fix.
+
+Constraints:
+Do not modify code.
+
+Validation:
+make fix
+make quality
+
+Logging requirements:
+- Update `docs/ai-worklog.md` and `docs/ai-prompts.md` using the standard log format.
+
+Execution Logging requirements:
+- Update docs/ai-execution-log.md with:
+  - full prompt
+  - agent todos
+  - final execution report
+
+Git requirements:
+- Do NOT commit or push unless explicitly requested.
+
+Expected Output:
+- diagnosis summary
+- proposed changes
+- expected file scope
+```
+
+---
+
+# Notes
+
+This template keeps AI interactions consistent across tasks and helps maintain a clean development history.

docs/ai-execution-log.md

@@ -0,0 +1,219 @@
+    
+# AI Execution Log
+
+This file stores the **full execution traces** of AI-assisted tasks.
+
+Unlike:
+- `docs/ai-worklog.md` → concise technical task summaries
+- `docs/ai-prompts.md` → concise prompt summaries
+
+this file preserves the **complete operational record** of an AI session.
+
+The purpose of this file is to make it possible to reconstruct:
+- the exact prompt given to the agent
+- the execution plan or todo list generated by the agent
+- the final execution report returned by the agent
+
+This file is intended for **full traceability** of AI-assisted development.
+
+Entries must be appended in chronological order.
+
+---
+
+## Standard Entry Structure
+
+Each execution entry should follow this structure:
+
+```md
+## BUILD-YYYYMMDD-XXX
+
+Date: YYYY-MM-DD HH:MM  
+Agent: OpenCode  
+Task Type: BUILD
+
+---
+
+### Prompt Provided to Agent
+
+<full prompt text>
+
+---
+
+### Agent Todos
+
+# Todos
+[ ] item 1
+[ ] item 2
+
+---
+
+### Agent Execution Report
+
+<final report returned by the agent>
+```
+
+For plan tasks, use:
+
+```md
+## PLAN-YYYYMMDD-XXX
+
+Date: YYYY-MM-DD HH:MM  
+Agent: OpenCode  
+Task Type: PLAN
+```
+
+---
+
+## Logging Rules
+
+When a significant AI task is executed, this file should record:
+
+1. The prompt that was actually given to the agent.
+2. The todo or execution plan shown by the agent.
+3. The final summary or execution report returned by the agent.
+
+Do not store private chain-of-thought.
+Only store user-visible execution artifacts.
+
+---
+
+## Relationship With Other Logs
+
+- `docs/ai-prompts.md` stores a concise summary of the prompt.
+- `docs/ai-worklog.md` stores a concise technical summary of what was done.
+- `docs/ai-execution-log.md` stores the complete visible execution trace.
+
+Together, the three files provide:
+
+1. Prompt intent
+2. Technical result
+3. Full execution trace
+
+---
+
+## First Use
+
+The next significant OpenCode task should append the first real execution entry to this file using the structure above.
+
+---
+
+## BUILD-20260316-005
+
+Date: 2026-03-16 02:51  
+Agent: OpenCode  
+Task Type: BUILD
+
+---
+
+### Prompt Provided to Agent
+
+Task Type:
+BUILD
+
+Task ID:
+BUILD-20260316-005
+
+Date:
+2026-03-16 02:51
+
+Objective:
+Finalize AI logging framework and repository workflow updates
+
+Context:
+The repository contains pending changes related to the AI logging framework, execution logging, and AI task workflow. These changes introduce a three-level logging system (`ai-worklog.md`, `ai-prompts.md`, and `ai-execution-log.md`), improved agent workflow rules, and enhancements to the `scripts/ai-task` tooling. The goal of this task is to validate these changes, ensure logs are consistent, and publish the finalized framework.
+
+Scope:
+- instructions-agent.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+- docs/ai-execution-log.md
+
+Requirements:
+1. Inspect the current working tree and confirm the changes in scope.
+2. Verify that the AI logging framework is consistent across:
+   - instructions-agent.md
+   - AGENT_WORKFLOW.md
+   - AI_TASK_TEMPLATE.md
+   - scripts/ai-task
+3. Ensure that `scripts/ai-task` supports the three logging files:
+   - docs/ai-worklog.md
+   - docs/ai-prompts.md
+   - docs/ai-execution-log.md
+4. Append a new AI BUILD ENTRY to `docs/ai-worklog.md`.
+5. Append a new BUILD PROMPT ENTRY to `docs/ai-prompts.md`.
+6. Append a new execution entry to `docs/ai-execution-log.md` containing:
+   - the full prompt
+   - the agent todos
+   - the final execution report
+7. Ensure all three logs remain in chronological order.
+8. Stage all modified files within the defined scope.
+9. Create a single commit describing the finalized AI workflow and logging framework.
+10. Push the commit to the current branch.
+
+Constraints:
+- follow AGENT_WORKFLOW.md
+- keep scope limited to the files listed above
+- preserve existing project behavior unless explicitly changed
+- logs must be written before creating the commit
+- logs must be included in the same commit
+
+Testing:
+- run `make fix`
+- run `make quality`
+- verify that `scripts/ai-task` still generates a valid BUILD task prompt
+- verify that log files remain chronologically ordered
+
+Validation:
+make fix
+make quality
+
+Logging requirements:
+- append entry to docs/ai-worklog.md
+- append entry to docs/ai-prompts.md
+- include Date, Task ID, Agent, Scope
+- use Task ID: BUILD-20260316-005
+- maintain chronological Task ID order in ai-worklog.md, ai-prompts.md and ai-execution-log.md
+- append entry to docs/ai-execution-log.md
+
+Execution Logging requirements:
+- append entry to docs/ai-execution-log.md
+- include:
+  - full prompt
+  - agent todos
+  - final execution report
+- use the standard execution log format defined in docs/ai-execution-log.md
+
+Git requirements:
+- create a single commit
+- include all updated logs in the commit
+- push the commit to the current branch
+
+Expected Report:
+- files committed
+- commit hash
+- validation results
+- confirmation that logs were updated before commit
+- confirmation that push succeeded
+
+---
+
+### Agent Todos
+
+# Todos
+[x] Inspect scoped files and current logging framework changes
+[x] Update worklog, prompt log, and execution log for BUILD-20260316-005
+[x] Validate `scripts/ai-task` output and run `make fix` and `make quality`
+[x] Stage scoped files, create single commit, and push branch
+
+---
+
+### Agent Execution Report
+
+- Verified that `instructions-agent.md`, `AGENT_WORKFLOW.md`, `AI_TASK_TEMPLATE.md`, and `scripts/ai-task` describe the same three-level logging workflow.
+- Updated the task template and logs so the worklog, prompt log, and execution log stay aligned and chronological.
+- Confirmed `scripts/ai-task build "test task" src/app/ui.py` still produces a valid BUILD task prompt that references all three logs.
+- Ran `make fix` and `make quality` successfully before commit creation.
+- Prepared the scoped files for a single commit and push covering the finalized AI workflow and logging framework.

docs/ai-prompts.md

@@ -1,43 +1,221 @@
 # AI Prompts Log
 
-This file stores relevant prompts used during AI-assisted development.
+This file stores the prompts that triggered significant AI-driven development tasks.
 
-Only store prompts that:
+The goal is to preserve traceability between:
+- the prompt given to the AI
+- the scope of the change
+- the resulting work recorded in `ai-worklog.md`
+
+Each entry must include:
+- Date (YYYY-MM-DD HH:MM)
+- Task ID
+- Agent
+- Task type (plan/build)
+- Scope
+- Prompt summary
+- Result summary
+
+Only record prompts that:
 - change architecture
 - introduce new behavior
 - modify important logic
 - affect project structure
 - debug complex issues
 
-Do not store internal chain-of-thought reasoning.
+Do not store chain-of-thought reasoning. Only store the prompt intent and a concise result summary.
-Store only the user prompt and a short result summary.
 
-## 2026-03-15
+---
 
-- prompt summary: Implement a dedicated history mode in `src/app/ui.py` so pressing `h` hides the tree, shows only history entries, supports Up/Down navigation, and uses Enter to select a history entry and return to the normal tree view.
+### BUILD PROMPT ENTRY
-- result summary: Added a dedicated history mode with its own selection state, removed the temporary overlay behavior, preserved existing `b`/`f` and normal tree navigation behavior, and added focused UI tests.
+Date: 2026-03-15 18:05
+Task ID: BUILD-20260315-001
+Agent: OpenCode
+Task: build
 
-## 2026-03-15
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
 
-- prompt summary: Introduce a mandatory AI logging system by updating `instructions-agent.md` and adding repository logs for AI work entries and prompt summaries.
+Prompt Summary:
-- result summary: Added enforceable AI logging rules to `instructions-agent.md`, created `docs/ai-worklog.md` and `docs/ai-prompts.md`, and established a traceable workflow for recording significant AI-assisted tasks.
+Implement a dedicated history mode in `src/app/ui.py` so pressing `h` hides the tree, shows only history entries, supports Up/Down navigation, and uses Enter to select a history entry and return to the normal tree view.
 
-## 2026-03-15
+Result Summary:
+Added a dedicated history mode with its own selection state, removed the temporary overlay behavior, preserved existing `b`/`f` and normal tree navigation behavior, and added focused UI tests.
 
-- prompt summary: Introduce a standard AI log entry format in `instructions-agent.md` and record the change in the repository AI logs.
+---
-- result summary: Added a standardized `AI BUILD ENTRY` and `AI PLAN ENTRY` format, improved consistency expectations for AI logs, and updated the log files to reflect the new format.
 
-## 2026-03-15
+### BUILD PROMPT ENTRY
+Date: 2026-03-15 19:25
+Task ID: BUILD-20260315-002
+Agent: OpenCode
+Task: build
 
-- prompt summary: Improve keyboard navigation in `src/app/ui.py` so Right expands or enters, Left collapses or goes to the parent, Enter confirms the selected destination, and ESC cancels back to the starting directory.
+Scope:
-- result summary: Updated the tree-mode key handling in the terminal UI, preserved history mode behavior, and added focused UI tests for the new navigation rules.
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
 
-## 2026-03-15
+Prompt Summary:
+Introduce a mandatory AI logging system by updating `instructions-agent.md` and adding repository logs for AI work entries and prompt summaries.
 
-- prompt summary: Improve vertical scrolling in `src/app/ui.py` so the selected entry always remains visible in tree mode and history mode when the list is taller than the screen.
+Result Summary:
-- result summary: Added UI scroll offset handling for tree and history views, kept existing navigation behavior unchanged, and added focused tests for the scroll helper logic.
+Added enforceable AI logging rules to `instructions-agent.md`, created `docs/ai-worklog.md` and `docs/ai-prompts.md`, and established a traceable workflow for recording significant AI-assisted tasks.
 
-## 2026-03-16 00:27
+---
 
-- prompt summary: Improve terminal UI navigation by refining tree and history keyboard behavior, adding scrolling continuity so selection stays visible, and preserving confirmation, cancellation, and history mode behavior.
+### BUILD PROMPT ENTRY
-- result summary: Updated `src/app/ui.py` and `tests/test_ui.py` to support dedicated history selection, improved Right/Left/Enter/ESC behavior, and vertical scrolling for both tree and history views while keeping the AI logs current.
+Date: 2026-03-15 20:00
+Task ID: BUILD-20260315-003
+Agent: OpenCode
+Task: build
+
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Prompt Summary:
+Introduce a standard AI log entry format in `instructions-agent.md` and record the change in the repository AI logs.
+
+Result Summary:
+Added standardized `AI BUILD ENTRY` and `AI PLAN ENTRY` formats, improving consistency and long-term traceability of AI-assisted development.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-15 21:35
+Task ID: BUILD-20260315-004
+Agent: OpenCode
+Task: build
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
+Prompt Summary:
+Improve keyboard navigation in `src/app/ui.py` so Right expands or enters, Left collapses or goes to the parent, Enter confirms the selected destination, and ESC cancels back to the starting directory.
+
+Result Summary:
+Updated the tree-mode key handling in the terminal UI, preserved history mode behavior, and added focused UI tests for the new navigation rules.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-15 22:20
+Task ID: BUILD-20260315-005
+Agent: OpenCode
+Task: build
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
+Prompt Summary:
+Improve vertical scrolling in `src/app/ui.py` so the selected entry always remains visible in tree mode and history mode when the list is taller than the screen.
+
+Result Summary:
+Added UI scroll offset handling for tree and history views, kept existing navigation behavior unchanged, and added focused tests for the scroll helper logic.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-16 00:27
+Task ID: BUILD-20260316-001
+Agent: OpenCode
+Task: build
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
+Prompt Summary:
+Refine terminal UI navigation, maintain dedicated history mode, and ensure scrolling continuity so selections remain visible.
+
+Result Summary:
+Updated terminal UI behavior, consolidated navigation improvements, and ensured consistent scrolling and selection visibility across tree and history modes.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-16 01:26
+Task ID: BUILD-20260316-002
+Agent: OpenCode
+Task: build
+
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Prompt Summary:
+Finalize the AI logging format system by requiring timestamped structured log entries and aligning the repository worklog and prompt log with the current logging framework.
+
+Result Summary:
+Updated the logging instructions, normalized the prompt log to the structured entry format, and added matching repository log entries for the finalized AI logging system.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-16 01:34
+Task ID: BUILD-20260316-003
+Agent: OpenCode
+Task: build
+
+Scope:
+- AGENT.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+
+Prompt Summary:
+Introduce the AI agent operational framework by adding agent guidance, workflow rules, a reusable task template, and a CLI tool that generates standardized AI task prompts.
+
+Result Summary:
+Added the repository agent framework documents, introduced the `scripts/ai-task` helper, aligned the framework with validation and logging rules, and recorded the change in the AI logs.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-16 01:45
+Task ID: BUILD-20260316-004
+Agent: OpenCode
+Task: build
+
+Scope:
+- instructions-agent.md
+- AGENT.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Prompt Summary:
+Finalize and publish the repository AI agent workflow and instruction framework by strengthening workflow and logging rules, documenting the agent framework files, and shipping the task generation tooling.
+
+Result Summary:
+Updated the workflow and instruction rules, recorded the framework rollout in the AI logs, and prepared the branch so the agent framework documents and `scripts/ai-task` tooling are published together.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-16 02:51
+Task ID: BUILD-20260316-005
+Agent: OpenCode
+Task: build
+
+Scope:
+- instructions-agent.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+- docs/ai-execution-log.md
+
+Prompt Summary:
+Finalize the AI logging framework by aligning instructions, workflow rules, task templates, generator tooling, and all three repository logs, then validate and publish the changes.
+
+Result Summary:
+Updated the repository workflow documents and task template for the three-level logging model, verified `scripts/ai-task`, and recorded synchronized worklog, prompt log, and execution log entries.

docs/ai-worklog.md

@@ -1,27 +1,40 @@
 # AI Worklog
 
-This file records important AI-assisted development actions.
+This file records important AI‑assisted development actions.
 
-Each entry should include:
+The log is designed for long‑term traceability of AI‑driven development.
-- date
-- task type (plan/build)
-- objective
-- files inspected or modified
-- key decisions
-- validation commands executed
-- result
-- open issues (if any)
 
-Entries must be concise and chronological.
+Each entry must include:
+- Date (YYYY-MM-DD HH:MM)
+- Task ID
+- Agent
+- Task type (plan/build)
+- Objective
+- Scope
+- Files Modified / Files Inspected
+- Key Decisions or Proposed Changes
+- Validation
+- Result
+- Open Issues
+
+Entries must remain chronological.
+
+---
 
 ### AI BUILD ENTRY
-Date: 2026-03-15  
+Date: 2026-03-15 18:10
-Task: build  
+Task ID: BUILD-20260315-001
+Agent: OpenCode
+Task: build
 Objective: Replace the temporary history debug overlay with a dedicated history mode in the terminal UI.
 
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
 Files Modified:
-- `src/app/ui.py`
+- src/app/ui.py
-- `tests/test_ui.py`
+- tests/test_ui.py
 
 Key Decisions:
 - Keep `b` and `f` unchanged.
@@ -34,131 +47,331 @@ Validation:
 - make quality
 
 Result:
-- History mode now shows only the history list, supports Up/Down selection, allows Enter to jump to a prior directory, and exits cleanly back to normal navigation.
+- History mode now shows only the history list and allows navigation and selection of past directories.
 
 Open Issues:
-- None.
+- None
+
+---
 
 ### AI BUILD ENTRY
-Date: 2026-03-16 00:27  
+Date: 2026-03-15 19:30
-Task: build  
+Task ID: BUILD-20260315-002
-Objective: Consolidate recent terminal UI navigation improvements and document the updated interaction behavior.
+Agent: OpenCode
+Task: build
+Objective: Introduce mandatory AI logging rules and repository logging workflow.
+
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
 
 Files Modified:
-- `src/app/ui.py`
+- instructions-agent.md
-- `tests/test_ui.py`
+- docs/ai-worklog.md
-- `docs/ai-worklog.md`
+- docs/ai-prompts.md
-- `docs/ai-prompts.md`
 
 Key Decisions:
-- Keep dedicated history mode while refining tree-mode keyboard behavior for Right, Left, Enter, and ESC.
+- Require AI agents to log plan and build tasks.
-- Add scroll continuity for both tree and history views so the selected row remains visible on long lists.
+- Separate logs for work results and prompts.
-- Cover the UI-focused behavior with helper-level tests instead of changing navigator or filesystem logic.
+- Keep entries concise and user‑focused.
-
-Validation:
-- make fix (passed)
-- make quality (passed)
-
-Result:
-- The terminal UI now combines dedicated history mode, clearer confirmation and cancellation behavior, improved tree navigation semantics, and vertical scrolling that keeps the current selection visible in both tree and history views.
-
-Open Issues:
-- None.
-
-### AI BUILD ENTRY
-Date: 2026-03-15  
-Task: build  
-Objective: Introduce mandatory AI logging rules and document the repository logging workflow.
-
-Files Modified:
-- `instructions-agent.md`
-- `docs/ai-worklog.md`
-- `docs/ai-prompts.md`
-
-Key Decisions:
-- Require AI agents to log significant plan and build tasks.
-- Preserve separate logs for work performed and prompts received.
-- Keep entries concise and user-facing.
 
 Validation:
 - not run
 
 Result:
-- The repository now defines mandatory AI logging in `instructions-agent.md` and includes dedicated log files for AI work history and prompt summaries.
+- Repository now enforces AI logging via instructions-agent.md.
 
 Open Issues:
-- None.
+- None
+
+---
 
 ### AI BUILD ENTRY
-Date: 2026-03-15  
+Date: 2026-03-15 20:05
-Task: build  
+Task ID: BUILD-20260315-003
-Objective: Record the introduction of the standard AI log entry format and improve AI logging consistency.
+Agent: OpenCode
+Task: build
+Objective: Introduce the standard AI log entry format and improve logging consistency.
+
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
 
 Files Modified:
-- `instructions-agent.md`
+- instructions-agent.md
-- `docs/ai-worklog.md`
+- docs/ai-worklog.md
-- `docs/ai-prompts.md`
+- docs/ai-prompts.md
 
 Key Decisions:
-- Add a dedicated "Standard AI Log Entry Format" section to define `AI BUILD ENTRY` and `AI PLAN ENTRY` blocks.
+- Define AI BUILD ENTRY and AI PLAN ENTRY blocks.
-- Use the new standardized format for this worklog update to establish the pattern in the repository logs.
+- Standardize structure for long‑term repository traceability.
 
 Validation:
 - make fix (passed)
 - make quality (passed)
 
 Result:
-- The repository now documents a standard AI log entry format and uses it to improve consistency of AI-assisted development logs.
+- Repository now uses a standardized AI logging format.
 
 Open Issues:
-- None.
+- None
+
+---
 
 ### AI BUILD ENTRY
-Date: 2026-03-15  
+Date: 2026-03-15 21:40
-Task: build  
+Task ID: BUILD-20260315-004
-Objective: Improve vertical scrolling in the terminal UI so the selected row remains visible in tree mode and history mode.
+Agent: OpenCode
-
+Task: build
-Files Modified:
-- `src/app/ui.py`
-- `tests/test_ui.py`
-- `docs/ai-worklog.md`
-- `docs/ai-prompts.md`
-
-Key Decisions:
-- Add separate scroll offsets for tree mode and history mode inside the UI state.
-- Introduce a small helper to clamp scroll offsets so the selected row always stays within the visible window.
-- Keep all existing navigation semantics unchanged while limiting the change to UI rendering behavior.
-
-Validation:
-- make fix (passed)
-- make quality (passed)
-
-Result:
-- The terminal UI now scrolls vertically in both tree mode and history mode to keep the current selection visible when the list is taller than the screen.
-
-Open Issues:
-- None.
-
-### AI BUILD ENTRY
-Date: 2026-03-15  
-Task: build  
 Objective: Improve keyboard navigation behavior in the terminal UI for tree mode.
 
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
 Files Modified:
-- `src/app/ui.py`
+- src/app/ui.py
-- `tests/test_ui.py`
+- tests/test_ui.py
 
 Key Decisions:
-- Make Right expand collapsed directories and enter already expanded directories.
+- Right expands collapsed directories and enters expanded directories.
-- Make Left collapse expanded directories and otherwise navigate to the parent directory.
+- Left collapses expanded directories or navigates to the parent directory.
-- Make Enter confirm the selected path as the final destination and make ESC return the original starting directory.
+- Enter confirms the selected path.
+- ESC cancels and returns to the original directory.
 
 Validation:
 - make fix (passed)
 - make quality (passed)
 
 Result:
-- Tree-mode keyboard navigation now supports expand-or-enter on Right, collapse-or-parent on Left, explicit selection confirmation on Enter, and cancel-to-start behavior on ESC.
+- Tree navigation semantics improved with clearer expand, enter, and cancel behavior.
 
 Open Issues:
-- None.
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-15 22:25
+Task ID: BUILD-20260315-005
+Agent: OpenCode
+Task: build
+Objective: Implement vertical scrolling so the selected entry always remains visible.
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
+Files Modified:
+- src/app/ui.py
+- tests/test_ui.py
+
+Key Decisions:
+- Introduce scroll offsets in the UI state.
+- Clamp offsets to keep the selected row visible.
+- Apply the same mechanism to history mode.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- Tree and history views now scroll when navigating beyond the visible screen area.
+
+Open Issues:
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-16 00:27
+Task ID: BUILD-20260316-001
+Agent: OpenCode
+Task: build
+Objective: Consolidate terminal UI navigation improvements and document updated behavior.
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Files Modified:
+- src/app/ui.py
+- tests/test_ui.py
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Key Decisions:
+- Maintain dedicated history mode.
+- Refine tree-mode keyboard behavior.
+- Keep UI logic isolated from navigator logic.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- Terminal UI now includes history mode, improved navigation semantics, and reliable vertical scrolling.
+
+Open Issues:
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-16 01:26
+Task ID: BUILD-20260316-002
+Agent: OpenCode
+Task: build
+Objective: Finalize the AI logging format system and align repository log files with the structured logging framework.
+
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Files Modified:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Key Decisions:
+- Require timestamped log entries with date and time, Task ID, Agent, and Scope fields.
+- Keep the worklog and prompt log aligned with the current structured logging framework.
+- Normalize prompt logging into a single consistent `BUILD PROMPT ENTRY` format.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- The AI logging system now uses consistent structured entries across repository instructions, worklog history, and prompt history.
+
+Open Issues:
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-16 01:34
+Task ID: BUILD-20260316-003
+Agent: OpenCode
+Task: build
+Objective: Introduce the AI agent operational framework and task generation tooling for standardized AI-assisted repository work.
+
+Scope:
+- AGENT.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+
+Files Modified:
+- AGENT.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Key Decisions:
+- Define separate documents for agent behavior, operational workflow, and reusable task structure.
+- Keep the task generator focused on producing standardized PLAN and BUILD prompts with task IDs and validation requirements.
+- Align the new framework with the repository logging rules and validation workflow.
+
+Validation:
+- scripts/ai-task build "test task" src/app/ui.py (passed)
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- The repository now includes a documented AI agent framework and an executable helper tool for generating standardized AI task prompts.
+
+Open Issues:
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-16 01:45
+Task ID: BUILD-20260316-004
+Agent: OpenCode
+Task: build
+Objective: Finalize and publish the AI agent workflow, instruction framework, and task tooling updates.
+
+Scope:
+- instructions-agent.md
+- AGENT.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Files Modified:
+- instructions-agent.md
+- AGENT_WORKFLOW.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Key Decisions:
+- Strengthen commit and logging order rules so AI logs must be written before creating commits.
+- Keep the new agent framework documents and task tooling aligned with the repository validation and traceability model.
+- Publish the previously prepared framework files together with the finalized logging guidance on the current branch.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- The repository now has a finalized AI instruction and workflow framework, standardized task tooling, and matching logs documenting the framework rollout.
+
+Open Issues:
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-16 02:51
+Task ID: BUILD-20260316-005
+Agent: OpenCode
+Task: build
+Objective: Finalize the three-level AI logging framework and repository workflow updates.
+
+Scope:
+- instructions-agent.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+- docs/ai-execution-log.md
+
+Files Modified:
+- instructions-agent.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+- docs/ai-execution-log.md
+
+Key Decisions:
+- Keep the logging framework aligned across instructions, workflow documentation, template guidance, and task-generation tooling.
+- Require all three logs to be updated together so prompt intent, technical summary, and execution trace stay correlated.
+- Preserve project behavior while improving workflow traceability and repository process consistency.
+
+Validation:
+- scripts/ai-task build "test task" src/app/ui.py (passed)
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- The repository now documents and validates a complete three-level AI logging workflow backed by updated instructions, workflow rules, task templates, and generator output.
+
+Open Issues:
+- None
+
+---

instructions-agent.md

@@ -67,6 +67,7 @@ This repository maintains an AI-assisted development log.
 Files:
 - `docs/ai-worklog.md`
 - `docs/ai-prompts.md`
+- `docs/ai-execution-log.md`
 
 Rules:
 1. After every significant `plan` or `build` task, append a concise worklog entry to `docs/ai-worklog.md`.
@@ -98,13 +99,25 @@ This applies to:
 Required files:
 - `docs/ai-worklog.md`
 - `docs/ai-prompts.md`
+- `docs/ai-execution-log.md`
 
 Mandatory rules:
 1. After every significant `plan` task, append a concise entry to `docs/ai-worklog.md`.
 2. After every significant `build` task, append a concise entry to `docs/ai-worklog.md`.
 3. If the task was driven by a meaningful prompt, also append an entry to `docs/ai-prompts.md`.
-4. Logging is part of the task itself and must not be skipped.
+4. The agent must append a full execution entry to `docs/ai-execution-log.md` including:
-5. The task is not complete until the logs are updated.
+   - the full prompt provided to the agent
+   - the agent todo list or execution plan
+   - the final execution report produced by the agent
+5. Logging is part of the task itself and must not be skipped.
+6. The task is not complete until the logs are updated.
+7. Logs must always be written **before creating a commit**.
+8. The agent must ensure that the following files are updated and staged before any commit:
+   - `docs/ai-worklog.md`
+   - `docs/ai-prompts.md`
+   - `docs/ai-execution-log.md`
+9. If a commit is created without the corresponding log entries, the task is considered incomplete and must be corrected.
+10. Log entries must be part of the same commit whenever possible to maintain traceability between the code change and the AI task that produced it.
 
 Each worklog entry must include:
 - date
@@ -121,6 +134,7 @@ Validation logging rule:
 - The value `validation: not run` may only be used if no validation commands were executed.
 - The worklog entry must reflect the actual commands run during the task.
 
+
 Each prompt log entry must include:
 - date
 - task type (`plan` or `build`)
@@ -134,6 +148,14 @@ Rules:
 - Keep entries chronological.
 - Even small but meaningful tasks must be logged.
 
+Execution log entries must include:
+- date
+- task ID
+- task type (`plan` or `build`)
+- full prompt text
+- agent todos
+- execution report
+
 ## Standard AI Log Entry Format
 
 To ensure consistency and readability of long AI-assisted development histories, all log entries must follow a standardized block format.
@@ -143,10 +165,16 @@ Agents must write log entries using the following structure.
 Example for build tasks:
 
 ### AI BUILD ENTRY
-Date: YYYY-MM-DD HH:MM  
+Date: YYYY-MM-DD HH:MM
-Task: build  
+Task ID: BUILD-YYYYMMDD-XXX
+Agent: OpenCode
+Task: build
 Objective: short description of the task
 
+Scope:
+- src/app/module.py
+- tests/test_module.py
+
 Files Modified:
 - file/path/example.py
 - another/file.md
@@ -167,10 +195,16 @@ Open Issues:
 Example for plan tasks:
 
 ### AI PLAN ENTRY
-Date: YYYY-MM-DD HH:MM  
+Date: YYYY-MM-DD HH:MM
-Task: plan  
+Task ID: PLAN-YYYYMMDD-XXX
+Agent: OpenCode
+Task: plan
 Objective: short description of planning objective
 
+Scope:
+- src/app/module.py
+- specs/module_spec.md
+
 Files Inspected:
 - src/app/example.py
 - specs/example_spec.md
@@ -188,3 +222,8 @@ Rules:
 - Use bullet points when possible.
 - This format must be used when updating `docs/ai-worklog.md`.
 - The Date field must include both date and time using the format YYYY-MM-DD HH:MM.
+- Every log entry must include a `Task ID`.
+- `Task ID` format must be `BUILD-YYYYMMDD-XXX` or `PLAN-YYYYMMDD-XXX`.
+- `Agent` must identify the tool or AI system performing the task (e.g., OpenCode).
+- `Scope` must describe the main files or project areas affected.
+- These fields make the AI worklog suitable for long-term traceability and large histories.

scripts/ai-task

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+
+# ai-task
+# Helper CLI to generate AI task prompts based on AI_TASK_TEMPLATE.md
+# Usage:
+#   scripts/ai-task build "Objective text" [scope...]
+#   scripts/ai-task plan "Objective text" [scope...]
+
+set -e
+
+TYPE="$1"
+OBJECTIVE="$2"
+shift 2 || true
+SCOPE=("$@")
+
+if [[ -z "$TYPE" || -z "$OBJECTIVE" ]]; then
+  echo "Usage: ai-task <plan|build> \"Objective\" [scope files...]"
+  exit 1
+fi
+
+TYPE_LOWER=$(echo "$TYPE" | tr '[:upper:]' '[:lower:]')
+TYPE_UPPER=$(echo "$TYPE_LOWER" | tr '[:lower:]' '[:upper:]')
+
+DATE=$(date "+%Y-%m-%d %H:%M")
+DAY=$(date "+%Y%m%d")
+
+case "$TYPE_LOWER" in
+  build)
+    PREFIX="BUILD"
+    ;;
+  plan)
+    PREFIX="PLAN"
+    ;;
+  *)
+    echo "Error: task type must be 'plan' or 'build'"
+    exit 1
+    ;;
+esac
+
+WORKLOG_FILE="docs/ai-worklog.md"
+PROMPTS_FILE="docs/ai-prompts.md"
+EXECUTION_LOG_FILE="docs/ai-execution-log.md"
+
+check_task_id_order() {
+  local file="$1"
+  local prefix="$2"
+  local previous=""
+  local current=""
+
+  [[ -f "$file" ]] || return 0
+
+  while IFS= read -r current; do
+    if [[ -n "$previous" && "$current" < "$previous" ]]; then
+      echo "Error: task IDs in $file are out of chronological order for prefix $prefix" >&2
+      echo "Previous: $previous" >&2
+      echo "Current:  $current" >&2
+      echo "Please fix the log order before generating a new task." >&2
+      exit 1
+    fi
+    previous="$current"
+  done < <(grep -Eo "${prefix}-[0-9]{8}-[0-9]{3}" "$file" || true)
+}
+
+check_task_id_order "$WORKLOG_FILE" "$PREFIX"
+check_task_id_order "$PROMPTS_FILE" "$PREFIX"
+check_task_id_order "$EXECUTION_LOG_FILE" "$PREFIX"
+
+LAST_SEQ=0
+
+if [[ -f "$WORKLOG_FILE" ]]; then
+  LAST_MATCH=$(grep -Eo "${PREFIX}-${DAY}-[0-9]{3}" "$WORKLOG_FILE" | tail -n 1 || true)
+  if [[ -n "$LAST_MATCH" ]]; then
+    LAST_SEQ=${LAST_MATCH##*-}
+    LAST_SEQ=$((10#$LAST_SEQ))
+  fi
+fi
+
+NEXT_SEQ=$(printf "%03d" $((LAST_SEQ + 1)))
+TASK_ID="${PREFIX}-${DAY}-${NEXT_SEQ}"
+
+# Build scope block
+cat <<EOF
+Task Type:
+${TYPE_UPPER}
+
+Task ID:
+${TASK_ID}
+
+Date:
+${DATE}
+
+Objective:
+${OBJECTIVE}
+
+Context:
+<describe repository state if needed>
+
+Scope:
+EOF
+
+if [ ${#SCOPE[@]} -gt 0 ]; then
+  for item in "${SCOPE[@]}"; do
+    printf '%s\n' "- ${item}"
+  done
+else
+  printf '%s\n' "- <fill scope>"
+fi
+
+cat <<EOF
+
+Requirements:
+<describe expected behavior>
+
+Constraints:
+- follow AGENT_WORKFLOW.md
+- keep scope minimal
+- preserve existing behavior unless explicitly changed
+
+Testing:
+<describe expected tests>
+
+Validation:
+make fix
+make quality
+
+Logging requirements:
+- append entry to docs/ai-worklog.md
+- append entry to docs/ai-prompts.md
+- include Date, Task ID, Agent, Scope
+- use Task ID: ${TASK_ID}
+- maintain chronological Task ID order in ai-worklog.md, ai-prompts.md and ai-execution-log.md
+- append entry to docs/ai-execution-log.md
+
+Execution Logging requirements:
+- append entry to docs/ai-execution-log.md
+- include:
+  - full prompt
+  - agent todos
+  - final execution report
+- use the standard execution log format defined in docs/ai-execution-log.md
+
+Git requirements:
+- do NOT commit or push unless explicitly requested
+
+Expected Report:
+- files changed
+- behavior changes
+- validation results
+EOF