feat: introduce AI agent framework and task tooling

- add AGENT.md describing the agent system
- add AGENT_WORKFLOW.md defining the execution workflow
- add AI_TASK_TEMPLATE.md for structured task prompts
- add scripts/ai-task CLI tool for generating standardized agent tasks

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,249 @@
+
+
+# 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`
+
+---
+
+# Standard Workflow
+
+Every AI task must follow this sequence:
+
+PLAN → REVIEW → BUILD → VALIDATE → LOG
+
+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.
+
+Two 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.
+
+---
+
+# 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-prompts.md
+- ai-worklog.md
+
+---
+
+# Commit Workflow
+
+Agents must **not commit or push automatically** unless explicitly instructed.
+
+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,145 @@
+# 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
+- Include Date, Task ID, Agent, Scope, Result
+
+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 ai-worklog.md and ai-prompts.md using the standard log format.
+```
+
+---
+
+# 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.
+
+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-prompts.md

@@ -1,43 +1,155 @@
 # 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.
-Store only the user prompt and a short result summary.
+Do not store chain-of-thought reasoning. Only store the prompt intent and a concise 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.
-- 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.
+### BUILD PROMPT ENTRY
+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.
-- 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.
+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.
 
-## 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.
-- 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.
+Scope:
+- 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: Added UI scroll offset handling for tree and history views, kept existing navigation behavior unchanged, and added focused tests for the scroll helper logic.
+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.
 
-## 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.
-- 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.
+### BUILD PROMPT ENTRY
+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.

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:
-- date
-- task type (plan/build)
-- objective
-- files inspected or modified
-- key decisions
-- validation commands executed
-- result
-- open issues (if any)
+The log is designed for long‑term traceability of AI‑driven development.
 
-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 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`
-- `tests/test_ui.py`
+- src/app/ui.py
+- tests/test_ui.py
 
 Key Decisions:
 - Keep `b` and `f` unchanged.
@@ -34,131 +47,208 @@ 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 ID: BUILD-20260315-002
+Agent: OpenCode
 Task: build
-Objective: Consolidate recent terminal UI navigation improvements and document the updated interaction behavior.
+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`
-- `tests/test_ui.py`
-- `docs/ai-worklog.md`
-- `docs/ai-prompts.md`
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
 
 Key Decisions:
-- Keep dedicated history mode while refining tree-mode keyboard behavior for Right, Left, Enter, and ESC.
-- Add scroll continuity for both tree and history views so the selected row remains visible on long lists.
-- Cover the UI-focused behavior with helper-level tests instead of changing navigator or filesystem logic.
-
-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.
+- Require AI agents to log plan and build tasks.
+- Separate logs for work results and prompts.
+- Keep entries concise and user‑focused.
 
 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 ID: BUILD-20260315-003
+Agent: OpenCode
 Task: build
-Objective: Record the introduction of the standard AI log entry format and improve AI logging consistency.
+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`
-- `docs/ai-worklog.md`
-- `docs/ai-prompts.md`
+- instructions-agent.md
+- docs/ai-worklog.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.
-- Use the new standardized format for this worklog update to establish the pattern in the repository logs.
+- Define AI BUILD ENTRY and AI PLAN ENTRY blocks.
+- 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  
-Task: build  
-Objective: Improve vertical scrolling in the terminal UI so the selected row remains visible in tree mode and history mode.
-
-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  
+Date: 2026-03-15 21:40
+Task ID: BUILD-20260315-004
+Agent: OpenCode
 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`
-- `tests/test_ui.py`
+- src/app/ui.py
+- tests/test_ui.py
 
 Key Decisions:
-- Make Right expand collapsed directories and enter already expanded directories.
-- Make Left collapse expanded directories and otherwise navigate to the parent directory.
-- Make Enter confirm the selected path as the final destination and make ESC return the original starting directory.
+- Right expands collapsed directories and enters expanded directories.
+- Left collapses expanded directories or navigates to the parent 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

instructions-agent.md

@@ -144,9 +144,15 @@ Example for build tasks:
 
 ### AI BUILD ENTRY
 Date: YYYY-MM-DD HH:MM
+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
@@ -168,9 +174,15 @@ Example for plan tasks:
 
 ### AI PLAN ENTRY
 Date: YYYY-MM-DD HH:MM
+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 +200,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,112 @@
+#!/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"
+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}
+
+Git requirements:
+- do NOT commit or push unless explicitly requested
+
+Expected Report:
+- files changed
+- behavior changes
+- validation results
+EOF