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_WORKFLOW.md

@@ -1,5 +1,3 @@
-
-
 # AGENT_WORKFLOW.md
 
 AI Agent Operational Workflow
@@ -19,6 +17,7 @@ This file complements:
 - `instructions-agent.md`
 - `docs/ai-worklog.md`
 - `docs/ai-prompts.md`
+- `docs/ai-execution-log.md`
 
 ---
 
@@ -28,6 +27,29 @@ 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.
 
 ---
@@ -119,7 +141,7 @@ Validation must pass before changes are considered complete.
 Goal:
 Record the AI activity for traceability.
 
-Two log files must be updated.
+Three log files must be updated.
 
 ### Work Log
 
@@ -164,6 +186,24 @@ Record:
 
 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
@@ -186,6 +226,7 @@ BUILD-20260316-002
 
 The same Task ID must appear in:
 
+- ai-execution-log.md
 - ai-prompts.md
 - ai-worklog.md
 
@@ -195,6 +236,14 @@ The same Task ID must appear in:
 
 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

AI_TASK_TEMPLATE.md

@@ -55,8 +55,17 @@ 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.
 
@@ -102,7 +111,16 @@ make fix
 make quality
 
 Logging requirements:
-Update ai-worklog.md and ai-prompts.md using the standard log format.
+- 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.
 ```
 
 ---
@@ -132,6 +150,22 @@ 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

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

@@ -153,3 +153,69 @@ Finalize the AI logging format system by requiring timestamped structured log en
 
 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

@@ -252,3 +252,126 @@ Result:
 
 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.
-5. The task is not complete until the logs are updated.
+4. The agent must append a full execution entry to `docs/ai-execution-log.md` including:
+   - 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.

scripts/ai-task

@@ -38,6 +38,33 @@ case "$TYPE_LOWER" in
 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
@@ -101,6 +128,16 @@ Logging requirements:
 - 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