chore: update AI platform integration

Update HLL Vietnam AI Platform integration with ai-platform.json, extended task lifecycle folders, config-aware runner, lightweight validation, report ignore rules, and platform documentation updates.
2026-05-19 08:43:56 +02:00
parent 22c7085a65
commit 50d11f0c34
15 changed files with 355 additions and 12 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -11,8 +11,11 @@ Thumbs.db

 # Local AI worker/runtime artifacts
 ai/worker.lock
+ai/reports/*.md
+!ai/reports/.gitkeep

 # Local backend runtime data
+backend/runtime/
 backend/data/*.sqlite3
 !backend/data/.gitkeep
 backend/data/snapshots/**
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,12 +17,19 @@ Task locations:

 - Pending: `ai/tasks/pending`
 - In progress: `ai/tasks/in-progress`
+- Review: `ai/tasks/review`
+- Blocked: `ai/tasks/blocked`
+- Obsolete: `ai/tasks/obsolete`
 - Done: `ai/tasks/done`

 Every new task must follow:

 - `ai/task-template.md`

+Local platform scripts should read repository-specific paths and worker settings from:
+
+- `ai-platform.json`
+
 ## Core Workflow

 1. The orchestrator reviews repository context and relevant code.
@@ -31,7 +38,7 @@ Every new task must follow:
 4. The worker reads the files listed in `Files to Read First`.
 5. The worker performs only the scoped change defined by the task.
 6. The worker validates the change with the documented checks.
-7. The worker moves the completed task to `ai/tasks/done`.
+7. The worker moves completed work to `ai/tasks/done` when validation is complete, or to `ai/tasks/review` when human/orchestrator review is explicitly required.
 8. The worker documents any relevant architectural or process decision.

 Codex must not act freely outside tasks except for repository inspection, platform maintenance, or explicitly requested integration work like this one.
--- a/ai-platform.json
+++ b/ai-platform.json
@@ -0,0 +1,34 @@
+{
+  "schema_version": 1,
+  "project": {
+    "name": "HLL Vietnam",
+    "type": "community website",
+    "identity": "Spanish-speaking HLL Vietnam Discord community",
+    "visual_direction": "military, Vietnam, tactical, sober"
+  },
+  "workflow": {
+    "orchestrator": "ChatGPT coordinates with the human client/product owner and prepares scoped tasks.",
+    "worker": "Codex CLI workers execute only explicit tasks and follow AGENTS.md.",
+    "task_template": "ai/task-template.md",
+    "task_paths": {
+      "pending": "ai/tasks/pending",
+      "in_progress": "ai/tasks/in-progress",
+      "review": "ai/tasks/review",
+      "blocked": "ai/tasks/blocked",
+      "obsolete": "ai/tasks/obsolete",
+      "done": "ai/tasks/done"
+    }
+  },
+  "runner": {
+    "lock_file": "ai/worker.lock",
+    "metrics_file": "ai/system-metrics.md",
+    "reports_path": "ai/reports",
+    "integration_tests_script": "scripts/run-integration-tests.ps1",
+    "codex_prompt": "Follow AGENTS.md, read the platform context in ai/, and process the pending tasks without acting outside task scope."
+  },
+  "constraints": {
+    "frontend": "Keep HTML, CSS and vanilla JavaScript compatible with direct browser opening when applicable.",
+    "backend": "Python is the planned backend baseline. Do not add backend behavior without a task.",
+    "scope": "Preserve HLL Vietnam context. Do not expand Elo/MMR, historical workers or RCON server #03 handling from platform tasks."
+  }
+}
--- a/ai/README.md
+++ b/ai/README.md
@@ -6,17 +6,29 @@ Its purpose is operational, not product-facing. It exists to help the project pl

 ## Included areas

+- `../ai-platform.json`: repository-specific platform configuration for local workers and validation
 - `task-template.md`: standard structure for every task
 - `repo-context.md`: repository and product context for planners and workers
 - `architecture-index.md`: quick map of the repository structure
 - `system-metrics.md`: lightweight log for platform execution metrics
+- `reports/`: generated local platform reports; Markdown reports are ignored except `.gitkeep`
 - `prompts/`: reusable planning prompts
 - `orchestrator/`: role guidance and orchestration documents
 - `tasks/`: task queue split by status

+## Task lifecycle
+
+- `tasks/pending/`: scoped tasks ready for a worker
+- `tasks/in-progress/`: tasks currently being executed
+- `tasks/review/`: completed work waiting for human or orchestrator review
+- `tasks/blocked/`: tasks that cannot continue without a decision or missing input
+- `tasks/obsolete/`: tasks intentionally retired without execution
+- `tasks/done/`: validated and completed tasks
+
 ## HLL Vietnam usage rules

 - The platform must reflect the real state of HLL Vietnam, not generic sample content.
 - Tasks should be created only when there is a justified change to perform.
 - This integration does not add product features by itself.
 - The current product stack remains HTML, CSS and JavaScript on the frontend, with Python reserved for the future backend.
+- Codex workers must process explicit tasks only and use `ai-platform.json` for local platform paths where scripts support it.
--- a/ai/architecture-index.md
+++ b/ai/architecture-index.md
@@ -12,6 +12,7 @@ Community website repository with a static landing in the current phase and a pl

 - `README.md`
 - `AGENTS.md`
+- `ai-platform.json`
 - `docs/current-hll-servers-source-plan.md`
 - `docs/`

@@ -32,6 +33,7 @@ Community website repository with a static landing in the current phase and a pl
 - `ai/`
 - `ai/orchestrator/`
 - `ai/prompts/`
+- `ai/reports/`
 - `ai/tasks/`

 ### Automation And Support
@@ -50,6 +52,7 @@ Community website repository with a static landing in the current phase and a pl

 - Product-facing changes usually start in `frontend/`.
 - Process and coordination changes usually start in `ai/`, `AGENTS.md` and `scripts/`.
+- Local AI worker configuration starts in `ai-platform.json`.
 - Backend changes must remain preparatory unless a task explicitly changes that scope.

 ## Validation Expectations
--- a/ai/repo-context.md
+++ b/ai/repo-context.md
@@ -56,9 +56,11 @@ This area is a reserved foundation for the future Python backend. Do not add fun
 ### AI Platform

 - `ai/task-template.md`
+- `ai-platform.json`
 - `ai/repo-context.md`
 - `ai/architecture-index.md`
 - `ai/system-metrics.md`
+- `ai/reports/`
 - `ai/prompts/`
 - `ai/orchestrator/`
 - `ai/tasks/`
@@ -81,4 +83,7 @@ Tasks move through:

 - `ai/tasks/pending`
 - `ai/tasks/in-progress`
+- `ai/tasks/review`
+- `ai/tasks/blocked`
+- `ai/tasks/obsolete`
 - `ai/tasks/done`
--- a/ai/reports/.gitkeep
+++ b/ai/reports/.gitkeep
@@ -0,0 +1 @@
+
--- a/ai/system-metrics.md
+++ b/ai/system-metrics.md
@@ -15,3 +15,4 @@ This file tracks lightweight execution history for the HLL Vietnam AI developmen
 Date | Task | Duration | Result | Notes
 2026-03-19 | TASK-001-platform-readiness-check | n/a | success | README y roadmap alineados con la integración actual de AI Platform; scripts clave presentes; no hay tests de integración configurados para este alcance.
 2026-03-19T13:59:33 | worker-cycle | 641.24 sec | success | codex-runner
+2026-05-19T08:39:12 | worker-cycle | 663.71 sec | success | codex-runner
--- a/ai/task-template.md
+++ b/ai/task-template.md
@@ -1,4 +1,15 @@
-# TASK-XXX
+---
+id: TASK-XXX
+title: Short task title
+status: pending
+type: platform | frontend | backend | documentation | research
+team: PM | Analista | Backend Senior | Frontend Senior | Arquitecto de Base de Datos | Arquitecto Python | Disenador grafico | Experto en interfaz
+supporting_teams: []
+roadmap_item: foundation
+priority: medium
+---
+
+# TASK-XXX - Short task title

 ## Goal

@@ -8,6 +19,8 @@ Describe the smallest useful objective for this task.

 Explain where the change happens in HLL Vietnam and why it is needed now.

+Preserve the current product identity: Spanish-speaking HLL Vietnam community, military/Vietnam/tactical/sober visual direction and controlled repository evolution.
+
 ## Steps

 1. Inspect the listed files first.
@@ -49,6 +62,8 @@ Rules:
 - Preserve HLL Vietnam project identity.
 - Do not introduce unnecessary frameworks or dependencies.
 - Do not implement backend functionality unless the task explicitly requires it.
+- Do not expand Elo/MMR, historical workers or RCON server #03 handling unless the task explicitly requires it.
+- Do not overwrite repository-specific context with generic platform template text.

 ## Validation

@@ -57,6 +72,12 @@ Before completing the task ensure:
 - scoped checks pass
 - no unrelated files were modified
 - documentation remains consistent with the repository state
+- `git diff --name-only` matches the expected scope
+- integration tests are run when relevant and configured
+
+## Outcome
+
+Document the validation performed, notable decisions, and any follow-up task that should be created instead of expanding this task.

 ## Change Budget

--- a/ai/tasks/blocked/.gitkeep
+++ b/ai/tasks/blocked/.gitkeep
@@ -0,0 +1 @@
+
--- a/ai/tasks/done/TASK-107-update-ai-platform-integration.md
+++ b/ai/tasks/done/TASK-107-update-ai-platform-integration.md
@@ -0,0 +1,180 @@
+# TASK-107 - Update AI Platform Integration
+
+## Goal
+
+Update the HLL Vietnam AI Platform infrastructure to align with the newer `ai-dev-platform-template` conventions while preserving this repository's product context, workflow discipline and HLL Vietnam-specific documentation.
+
+This is platform infrastructure work only. It must not change product behavior, backend logic, frontend behavior, Docker deployment behavior, Elo/MMR logic or RCON server #03 handling.
+
+## Context
+
+HLL Vietnam currently has a lightweight AI Platform layer under `ai/`, root `AGENTS.md`, task lifecycle folders and local Codex worker support. The next platform update should move the repository toward a controlled development-team workflow where ChatGPT acts as orchestrator between the human client/product owner and the development team, and Codex CLI workers execute only explicit tasks.
+
+Important current direction:
+
+- The Elo/MMR system is paused for now because it is too complex for the current phase.
+- Comunidad Hispana / RCON server #03 is obsolete for future planning unless explicitly reintroduced.
+- Historical workers and complex ranking/materialization pipelines must not be expanded by this task.
+- The priority is to update AI Platform conventions safely and incrementally.
+
+Generic template text must be adapted to HLL Vietnam. Do not overwrite repository-specific context with generic `ai-dev-platform-template` content.
+
+## Steps
+
+1. Inspect the current platform files listed in `Files to Read First`.
+2. Compare the current repository conventions conceptually with the newer `ai-dev-platform-template` conventions:
+   - root `ai-platform.json`
+   - task lifecycle folders:
+     - `ai/tasks/pending`
+     - `ai/tasks/in-progress`
+     - `ai/tasks/review`
+     - `ai/tasks/blocked`
+     - `ai/tasks/obsolete`
+     - `ai/tasks/done`
+   - metadata-based task template with front matter:
+     - `id`
+     - `title`
+     - `status`
+     - `type`
+     - `team`
+     - `supporting_teams`
+     - `roadmap_item`
+     - `priority`
+   - config-aware `scripts/codex-runner.ps1`
+   - `scripts/run-integration-tests.ps1`
+   - optional `.github/workflows/codex-worker.yml`
+   - `ai/reports/.gitkeep`
+   - generated report ignore rules
+3. Add `ai-platform.json` adapted to HLL Vietnam. Include repository-specific task paths, project identity and workflow configuration needed by local platform scripts.
+4. Add missing task lifecycle directories with `.gitkeep` files where needed.
+5. Add `ai/reports/.gitkeep` if the reports directory is introduced or missing.
+6. Update `ai/task-template.md` to the newer metadata-based format while keeping HLL Vietnam-specific instructions, constraints and validation expectations.
+7. Update `scripts/codex-runner.ps1` so it reads platform configuration from `ai-platform.json` instead of relying only on hard-coded repository assumptions.
+8. Add or update `scripts/run-integration-tests.ps1` with repository-appropriate lightweight validation. The script should fail safely when optional checks are not configured.
+9. Add `.github/workflows/codex-worker.yml` only if it is consistent with the current repository automation policy and does not create unintended deployment or product behavior.
+10. Update `.gitignore` to ignore local runtime and generated platform artifacts, including:
+    - `backend/runtime/`
+    - generated `ai/reports/*.md` files
+    - keep `ai/reports/.gitkeep` trackable
+11. Update `AGENTS.md`, `ai/README.md`, `ai/repo-context.md` and/or `ai/architecture-index.md` only where necessary to reflect the new platform workflow.
+12. Document any relevant architectural or process decisions in the task outcome.
+
+## Files to Read First
+
+- `AGENTS.md`
+- `README.md`
+- `.gitignore`
+- `ai/README.md`
+- `ai/repo-context.md`
+- `ai/architecture-index.md`
+- `ai/task-template.md`
+- `scripts/codex-runner.ps1`
+- `docker-compose.yml`
+- `.github/workflows/*` if present
+
+Rules:
+
+- Read these files before implementation.
+- Keep product behavior unchanged.
+- Use the existing HLL Vietnam context as the source of truth.
+- Treat template conventions as a reference, not content to copy blindly.
+
+## Expected Files to Modify
+
+Likely files:
+
+- `ai-platform.json`
+- `.gitignore`
+- `AGENTS.md`
+- `ai/README.md`
+- `ai/repo-context.md`
+- `ai/architecture-index.md`
+- `ai/task-template.md`
+- `scripts/codex-runner.ps1`
+- `scripts/run-integration-tests.ps1`
+- `ai/tasks/review/.gitkeep`
+- `ai/tasks/blocked/.gitkeep`
+- `ai/tasks/obsolete/.gitkeep`
+- `ai/reports/.gitkeep`
+
+Possible file, only if consistent with the repository automation policy:
+
+- `.github/workflows/codex-worker.yml`
+
+Rules:
+
+- Do not modify product files unless there is a platform-only reason and it is documented.
+- Do not modify unrelated files.
+- If additional files become necessary, explain why in the task outcome.
+
+## Expected Files Not To Modify
+
+- `backend/**` product logic
+- `frontend/**`
+- `docker-compose.yml`
+- Elo/MMR implementation files
+- RCON server #03 implementation or configuration
+
+## Constraints
+
+- This task is platform infrastructure work, not product work.
+- Do not change frontend behavior.
+- Do not change backend behavior.
+- Do not change Docker deployment behavior.
+- Do not change Elo/MMR code or expand Elo/MMR pipelines.
+- Do not remove, rename or alter RCON server #03 in this task.
+- Do not expand historical workers or complex ranking/materialization pipelines.
+- Preserve HLL Vietnam-specific project context, Spanish-speaking community identity and current repository direction.
+- Adapt template conventions to this repository instead of blindly copying generic template text.
+- Keep the change narrow, reviewable and implementation-ready.
+
+## Validation
+
+Before completing the task ensure:
+
+- `git status` has been reviewed.
+- `git diff --name-only` shows only expected platform files.
+- `ai-platform.json` exists and is valid JSON.
+- The task lifecycle folders exist:
+  - `ai/tasks/pending`
+  - `ai/tasks/in-progress`
+  - `ai/tasks/review`
+  - `ai/tasks/blocked`
+  - `ai/tasks/obsolete`
+  - `ai/tasks/done`
+- Required empty platform directories contain `.gitkeep` files where needed.
+- Generated reports such as `ai/reports/*.md` are ignored by Git.
+- `ai/reports/.gitkeep` remains trackable.
+- `backend/runtime/` is ignored by Git.
+- No local runtime data is committed.
+- A lightweight repository validation command has been run if available.
+- If `scripts/run-integration-tests.ps1` exists after the change, run it.
+- If no integration tests are configured for the affected scope, document that explicitly in the task outcome.
+- Frontend, backend and Docker behavior remain unchanged.
+
+## Change Budget
+
+- Prefer fewer than 10 modified files for this platform update.
+- Prefer small documentation and script changes over broad rewrites.
+- Split follow-up work into separate tasks if the scope grows beyond platform integration.
+
+## Outcome
+
+- Added repository-specific `ai-platform.json` for task paths, worker settings and HLL Vietnam constraints.
+- Added missing lifecycle folders: `review`, `blocked` and `obsolete`.
+- Added `ai/reports/.gitkeep` and ignored generated `ai/reports/*.md` files while keeping `.gitkeep` trackable.
+- Updated the task template to include metadata front matter and HLL Vietnam-specific constraints.
+- Updated `scripts/codex-runner.ps1` to read local worker paths and prompts from `ai-platform.json`.
+- Updated `scripts/run-integration-tests.ps1` to perform lightweight platform validation only.
+- Updated platform documentation in `AGENTS.md`, `ai/README.md`, `ai/repo-context.md` and `ai/architecture-index.md`.
+- No frontend, backend product logic, Docker behavior, Elo/MMR logic or RCON server #03 handling was changed.
+
+Validation performed:
+
+- Parsed `ai-platform.json` with `ConvertFrom-Json`.
+- Ran `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`.
+- Parsed both PowerShell scripts with the PowerShell language parser.
+- Confirmed `ai/reports/example.md` is ignored and `ai/reports/.gitkeep` is trackable.
+- Reviewed `git diff --name-only` and `git status --short`.
+
+No product integration tests are configured for this platform-only scope.
--- a/ai/tasks/obsolete/.gitkeep
+++ b/ai/tasks/obsolete/.gitkeep
@@ -0,0 +1 @@
+
--- a/ai/tasks/review/.gitkeep
+++ b/ai/tasks/review/.gitkeep
@@ -0,0 +1 @@
+
--- a/scripts/codex-runner.ps1
+++ b/scripts/codex-runner.ps1
@@ -2,9 +2,38 @@ param(
    [int]$PollIntervalSeconds = 30
 )

-Write-Host "HLL Vietnam Codex worker started..."
+$configPath = "ai-platform.json"

-$lockFile = "ai/worker.lock"
+function Get-PlatformConfig {
+    param(
+        [string]$Path
+    )
+
+    if (-not (Test-Path $Path)) {
+        return $null
+    }
+
+    try {
+        return Get-Content -Raw $Path | ConvertFrom-Json
+    }
+    catch {
+        Write-Host "Unable to read $Path. Falling back to default worker paths."
+        return $null
+    }
+}
+
+$platformConfig = Get-PlatformConfig -Path $configPath
+$projectName = if ($platformConfig.project.name) { $platformConfig.project.name } else { "HLL Vietnam" }
+$taskPaths = $platformConfig.workflow.task_paths
+$runnerConfig = $platformConfig.runner
+
+$pendingTasksPath = if ($taskPaths.pending) { $taskPaths.pending } else { "ai/tasks/pending" }
+$lockFile = if ($runnerConfig.lock_file) { $runnerConfig.lock_file } else { "ai/worker.lock" }
+$metricsFile = if ($runnerConfig.metrics_file) { $runnerConfig.metrics_file } else { "ai/system-metrics.md" }
+$integrationTestsScript = if ($runnerConfig.integration_tests_script) { $runnerConfig.integration_tests_script } else { "scripts/run-integration-tests.ps1" }
+$codexPrompt = if ($runnerConfig.codex_prompt) { $runnerConfig.codex_prompt } else { "Follow AGENTS.md, read the platform context in ai/, and process the pending tasks without acting outside task scope." }
+
+Write-Host "$projectName Codex worker started..."

 function Test-WorkerProcessActive {
    param(
@@ -43,7 +72,7 @@ while ($true) {
        Remove-Item $lockFile -Force -ErrorAction SilentlyContinue
    }

-    $pendingTasks = Get-ChildItem "ai/tasks/pending" -Filter *.md -ErrorAction SilentlyContinue
+    $pendingTasks = Get-ChildItem $pendingTasksPath -Filter *.md -ErrorAction SilentlyContinue

    if (-not $pendingTasks) {
        Write-Host "No pending tasks found."
@@ -60,19 +89,19 @@ while ($true) {

    try {
        $startTime = Get-Date
-        codex "Follow AGENTS.md, read the platform context in ai/, and process the pending tasks without acting outside task scope."
+        codex $codexPrompt
        $codexExitCode = $LASTEXITCODE
        $duration = [math]::Round(((Get-Date) - $startTime).TotalSeconds, 2)

        if ($codexExitCode -eq 0) {
-            Add-Content "ai/system-metrics.md" "$(Get-Date -Format s) | worker-cycle | $duration sec | success | codex-runner"
+            Add-Content $metricsFile "$(Get-Date -Format s) | worker-cycle | $duration sec | success | codex-runner"

-            if (Test-Path "scripts/run-integration-tests.ps1") {
-                powershell -ExecutionPolicy Bypass -File "scripts/run-integration-tests.ps1"
+            if (Test-Path $integrationTestsScript) {
+                powershell -ExecutionPolicy Bypass -File $integrationTestsScript
            }
        }
        else {
-            Add-Content "ai/system-metrics.md" "$(Get-Date -Format s) | worker-cycle | $duration sec | failed($codexExitCode) | codex-runner"
+            Add-Content $metricsFile "$(Get-Date -Format s) | worker-cycle | $duration sec | failed($codexExitCode) | codex-runner"
        }
    }
    finally {
--- a/scripts/run-integration-tests.ps1
+++ b/scripts/run-integration-tests.ps1
@@ -1,3 +1,47 @@
-Write-Host "HLL Vietnam integration validation"
-Write-Host "No integration tests are configured for the current repository scope."
+$ErrorActionPreference = "Stop"
+
+Write-Host "HLL Vietnam platform validation"
+
+$configPath = "ai-platform.json"
+if (-not (Test-Path $configPath)) {
+    throw "Missing $configPath"
+}
+
+$config = Get-Content -Raw $configPath | ConvertFrom-Json
+$taskPaths = $config.workflow.task_paths
+
+$requiredTaskPaths = @(
+    $taskPaths.pending,
+    $taskPaths.in_progress,
+    $taskPaths.review,
+    $taskPaths.blocked,
+    $taskPaths.obsolete,
+    $taskPaths.done
+)
+
+foreach ($path in $requiredTaskPaths) {
+    if (-not $path -or -not (Test-Path $path)) {
+        throw "Missing task lifecycle path: $path"
+    }
+}
+
+$gitignore = Get-Content -Raw ".gitignore"
+$requiredIgnoreRules = @(
+    "backend/runtime/",
+    "ai/reports/*.md",
+    "!ai/reports/.gitkeep"
+)
+
+foreach ($rule in $requiredIgnoreRules) {
+    if ($gitignore -notmatch [regex]::Escape($rule)) {
+        throw "Missing .gitignore rule: $rule"
+    }
+}
+
+if (-not (Test-Path "ai/reports/.gitkeep")) {
+    throw "Missing ai/reports/.gitkeep"
+}
+
+Write-Host "No product integration tests are configured for this platform-only scope."
+Write-Host "Platform validation passed."
 exit 0