agentic-dev 0.1.0 → 0.2.0

package/.codex/skills/otro/schemas/step_plan.schema.json

@@ -0,0 +1,289 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "run_name",
+    "plan_version",
+    "goal",
+    "summary",
+    "anchor_alignment",
+    "relevant_files",
+    "assumptions",
+    "risks",
+    "open_questions",
+    "completion_policy",
+    "tasks",
+    "steps"
+  ],
+  "properties": {
+    "run_name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "plan_version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "goal": {
+      "type": "string",
+      "minLength": 1
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "anchor_alignment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "notes"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "aligned",
+            "drifted"
+          ]
+        },
+        "notes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "relevant_files": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "reason"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "risks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "open_questions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "completion_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "done_when",
+        "loop_done",
+        "run_done",
+        "repository_done",
+        "replan_when"
+      ],
+      "properties": {
+        "done_when": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "loop_done": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "run_done": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "repository_done": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "replan_when": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "step",
+          "kind",
+          "title",
+          "objective",
+          "owned_paths",
+          "read_paths",
+          "depends_on",
+          "deliverables",
+          "acceptance_criteria",
+          "verification_commands",
+          "status",
+          "worker_prompt"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^T[0-9]{3,9}$"
+          },
+          "step": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "analysis",
+              "edit",
+              "verify",
+              "integration",
+              "cleanup",
+              "planning"
+            ]
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "objective": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owned_paths": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "read_paths": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "depends_on": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^T[0-9]{3,9}$"
+            }
+          },
+          "deliverables": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            }
+          },
+          "acceptance_criteria": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            }
+          },
+          "verification_commands": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "running",
+              "completed",
+              "blocked",
+              "failed",
+              "skipped"
+            ]
+          },
+          "worker_prompt": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "step",
+          "goal",
+          "task_ids",
+          "merge_checks"
+        ],
+        "properties": {
+          "step": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "goal": {
+            "type": "string",
+            "minLength": 1
+          },
+          "task_ids": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "^T[0-9]{3,9}$"
+            }
+          },
+          "merge_checks": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/.codex/skills/otro/schemas/task_result.schema.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "task_id",
+    "status",
+    "summary",
+    "changed_files",
+    "verification",
+    "blockers",
+    "integration_notes",
+    "proposed_follow_up_tasks",
+    "residual_signals"
+  ],
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "pattern": "^T[0-9]{3,9}$"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "completed",
+        "partial",
+        "blocked",
+        "failed"
+      ]
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "changed_files": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "verification": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "command",
+          "status",
+          "details"
+        ],
+        "properties": {
+          "command": {
+            "type": "string",
+            "minLength": 1
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "passed",
+              "failed",
+              "not_run"
+            ]
+          },
+          "details": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "blockers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "integration_notes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "residual_signals": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "proposed_follow_up_tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "title",
+          "kind",
+          "objective",
+          "owned_paths",
+          "depends_on",
+          "reason"
+        ],
+        "properties": {
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "analysis",
+              "edit",
+              "verify",
+              "integration",
+              "cleanup",
+              "planning"
+            ]
+          },
+          "objective": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owned_paths": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "depends_on": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^T[0-9]{3,9}$"
+            }
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

package/.codex/skills/otro/schemas/wave_plan.schema.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "./step_plan.schema.json"
+}

package/.codex/skills/otro/scripts/README.md

@@ -0,0 +1,38 @@
+Validation Header Bump Helper
+================================
+
+Purpose
+- Reduce manual drift by automating the header section of the durable OTRO validation guide.
+- Fields managed:
+  - `Status:` (optional replacement or token update)
+  - `Last updated:` (always refreshed)
+
+Script
+- Path: `.codex/skills/otro/scripts/bump_validation_header.py`
+- Default target file:
+  `.codex/skills/otro/validation/validation.md`
+
+Local usage
+- Dry‑run preview:
+  `python .codex/skills/otro/scripts/bump_validation_header.py --dry-run`
+- Replace both fields explicitly:
+  `python .codex/skills/otro/scripts/bump_validation_header.py --status "loop 20 complete" --task-id T900123 --timezone Asia/Seoul`
+- Only refresh date and add/update task token:
+  `python .codex/skills/otro/scripts/bump_validation_header.py --task-id T900123`
+
+GitHub Actions (manual)
+- Workflow: `.github/workflows/bump_validation_header.yml`
+- Trigger via “Run workflow” and optionally supply:
+  - `status` (without the leading `Status:`)
+  - `task_id` (e.g., `T900123`)
+  - `path` (override target path if needed)
+
+Commit policy
+- The workflow commits only when the file actually changes, with message:
+  `docs(validation): bump header [skip ci]`
+- It targets the branch used to trigger the workflow (typ. `main`).
+
+Notes
+- Timezone defaults to `Asia/Seoul` to match the template's SDD/admin validation docs.
+- If the `Status:` line already contains a `(Txxxxxx)` token, providing `--task-id` replaces it; otherwise the token is appended.
+- If the `Last updated:` key is missing, it is inserted immediately after the `Status:` line.

package/.codex/skills/otro/scripts/bump_validation_header.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+Small helper to bump the header of validation.md.
+
+Updates the following keys near the top of the file:
+  - "Status:" (optional replacement)
+  - "Last updated:" (always refreshed)
+
+Usage (local):
+  python .codex/skills/otro/scripts/bump_validation_header.py \
+    --file .codex/skills/otro/validation/validation.md \
+    --status "loop 20 complete" --task-id T900123 --timezone Asia/Seoul
+
+Workflow usage: see .github/workflows/bump_validation_header.yml
+
+Notes:
+- If --status is omitted, the existing Status line is preserved.
+- If --task-id is provided without --status, the helper replaces or appends
+  the trailing (Txxxxxx) token in the existing Status line.
+- The Last updated line is set to YYYY-MM-DD (TZNAME), defaulting to Asia/Seoul.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+try:
+    from zoneinfo import ZoneInfo  # Python 3.9+
+except Exception:  # pragma: no cover
+    ZoneInfo = None  # type: ignore
+
+
+HEADER_STATUS_RE = re.compile(r"^Status:\s*(?P<value>.*)$")
+HEADER_UPDATED_RE = re.compile(r"^Last updated:\s*(?P<value>.*)$")
+TASK_TOKEN_RE = re.compile(r"\(T\d+\)")
+
+
+@dataclass
+class HeaderUpdate:
+    line_no: int
+    old: str
+    new: str
+
+
+def _now_str(tz_name: str) -> str:
+    tz_display = tz_name
+    if ZoneInfo is not None:
+        try:
+            tz = ZoneInfo(tz_name)
+            now = datetime.now(tz)
+        except Exception:
+            now = datetime.now(timezone.utc)
+            tz_display = "UTC"
+    else:
+        now = datetime.utcnow().replace(tzinfo=timezone.utc)
+        tz_display = "UTC"
+    return f"{now.strftime('%Y-%m-%d')} ({tz_display})"
+
+
+def bump_header(
+    path: str,
+    status: str | None,
+    task_id: str | None,
+    tz_name: str,
+) -> list[HeaderUpdate]:
+    with open(path, "r", encoding="utf-8") as f:
+        lines = f.readlines()
+
+    updates: list[HeaderUpdate] = []
+
+    # Search only the early header area (first 60 lines) for safety.
+    header_limit = min(60, len(lines))
+    status_idx = updated_idx = None
+
+    for i in range(header_limit):
+        if status_idx is None and HEADER_STATUS_RE.match(lines[i]):
+            status_idx = i
+        if updated_idx is None and HEADER_UPDATED_RE.match(lines[i]):
+            updated_idx = i
+        if status_idx is not None and updated_idx is not None:
+            break
+
+    # Compute new Status line text if requested or task_id given.
+    if status_idx is not None:
+        m = HEADER_STATUS_RE.match(lines[status_idx])
+        assert m
+        current_status = m.group("value").strip()
+        new_status = current_status
+        if status is not None:
+            new_status = status.strip()
+            if task_id and not TASK_TOKEN_RE.search(new_status):
+                new_status = f"{new_status} ({task_id})"
+        elif task_id:
+            # Replace trailing (Txxxx) if present; else append.
+            if TASK_TOKEN_RE.search(current_status):
+                new_status = TASK_TOKEN_RE.sub(f"({task_id})", current_status)
+            else:
+                new_status = f"{current_status} ({task_id})"
+
+        if new_status != current_status:
+            new_line = f"Status: {new_status}\n"
+            updates.append(HeaderUpdate(status_idx + 1, lines[status_idx], new_line))
+            lines[status_idx] = new_line
+
+    # Always update Last updated
+    updated_value = _now_str(tz_name)
+    if updated_idx is not None:
+        old_line = lines[updated_idx]
+        new_line = f"Last updated: {updated_value}\n"
+        if old_line != new_line:
+            updates.append(HeaderUpdate(updated_idx + 1, old_line, new_line))
+            lines[updated_idx] = new_line
+    else:
+        # If no Last updated, insert after Status (or line 2)
+        insert_at = (status_idx + 1) if status_idx is not None else 1
+        new_line = f"Last updated: {updated_value}\n"
+        lines.insert(insert_at, new_line)
+        updates.append(HeaderUpdate(insert_at + 1, "<insert>", new_line))
+
+    if updates:
+        with open(path, "w", encoding="utf-8") as f:
+            f.writelines(lines)
+
+    return updates
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Bump validation.md header fields")
+    parser.add_argument(
+        "--file",
+        default=(
+            ".codex/skills/otro/validation/validation.md"
+        ),
+        help="Path to validation.md",
+    )
+    parser.add_argument("--status", help="New Status value (without leading 'Status:')")
+    parser.add_argument("--task-id", dest="task_id", help="Task ID like T900123")
+    parser.add_argument(
+        "--timezone",
+        default=os.environ.get("VALIDATION_TZ", "Asia/Seoul"),
+        help="IANA timezone name for Last updated (default: Asia/Seoul)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would change but do not modify the file",
+    )
+
+    args = parser.parse_args()
+
+    if args.dry_run:
+        # Copy to a temp buffer to preview without persisting.
+        with open(args.file, "r", encoding="utf-8") as f:
+            original = f.read()
+        updates = bump_header(args.file, args.status, args.task_id, args.timezone)
+        # Restore original content after preview.
+        with open(args.file, "w", encoding="utf-8") as f:
+            f.write(original)
+    else:
+        updates = bump_header(args.file, args.status, args.task_id, args.timezone)
+
+    if not updates:
+        print("No header changes were necessary.")
+        return 0
+
+    print("Updated lines:")
+    for u in updates:
+        old = u.old.rstrip("\n")
+        new = u.new.rstrip("\n")
+        print(f"  {u.line_no}: '{old}' -> '{new}'")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())