diff --git a/.gitea/ISSUE_TEMPLATE/runtime_verification.md b/.gitea/ISSUE_TEMPLATE/runtime_verification.md new file mode 100644 index 0000000..3e27fda --- /dev/null +++ b/.gitea/ISSUE_TEMPLATE/runtime_verification.md @@ -0,0 +1,41 @@ +--- +name: Runtime Verification Incident +about: 실운영/스테이징 동작 검증 중 발견된 이상 징후 등록 +title: "[RUNTIME-VERIFY][SCN-XXX] " +labels: runtime, verification +--- + +## Summary + +- 현상: +- 최초 관측 시각(UTC): + +## Reproduction / Observation + +- 실행 모드(`live`/`paper`): +- 세션(`NXT`, `US_PRE`, `US_DAY`, `US_AFTER`, ...): +- 실행 커맨드: +- 로그 경로: + +## Expected vs Actual + +- Expected: +- Actual: + +## Requirement Mapping + +- REQ: +- TASK: +- TEST: + +## Temporary Mitigation + +- 즉시 완화책: + +## Close Criteria + +- [ ] Dev 수정 반영 +- [ ] Verifier 재검증 PASS +- [ ] Runtime Verifier 재관측 PASS +- [ ] `NOT_OBSERVED = 0` + diff --git a/.gitea/PULL_REQUEST_TEMPLATE.md b/.gitea/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..99f5345 --- /dev/null +++ b/.gitea/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,38 @@ +## Linked Issue + +- Closes #N + +## Scope + +- REQ: `REQ-...` +- TASK: `TASK-...` +- TEST: `TEST-...` + +## Main -> Verifier Directive Contract + +- Scope: 대상 요구사항/코드/로그 경로 +- Method: 실행 커맨드 + 관측 포인트 +- PASS criteria: +- FAIL criteria: +- NOT_OBSERVED criteria: +- Evidence format: PR 코멘트 `Coverage Matrix` + +## Verifier Coverage Matrix (Required) + +| Item | Evidence | Status (PASS/FAIL/NOT_OBSERVED) | +|---|---|---| +| REQ-... | 링크/로그 | PASS | + +`NOT_OBSERVED`가 1개라도 있으면 승인/머지 금지. + +## Gitea Preflight + +- [ ] `docs/commands.md`와 `docs/workflow.md` 트러블슈팅 선확인 +- [ ] `tea` 사용 (`gh` 미사용) + +## Runtime Evidence + +- 시스템 실제 구동 커맨드: +- 모니터링 로그 경로: +- 이상 징후/이슈 링크: + diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6fcd55a..756de37 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,6 +21,12 @@ jobs: - name: Install dependencies run: pip install ".[dev]" + - name: Validate governance assets + run: python3 scripts/validate_governance_assets.py + + - name: Validate Ouroboros docs + run: python3 scripts/validate_ouroboros_docs.py + - name: Lint run: ruff check src/ tests/ diff --git a/docs/agent-constraints.md b/docs/agent-constraints.md index 6d50b67..0e955fb 100644 --- a/docs/agent-constraints.md +++ b/docs/agent-constraints.md @@ -12,6 +12,8 @@ It is distinct from `docs/requirements-log.md`, which records **project/product 1. **Workflow enforcement** - Follow `docs/workflow.md` for all changes. + - Before any Gitea issue/PR/comment operation, read `docs/commands.md` and `docs/workflow.md` troubleshooting section. + - Use `tea` for Gitea operations; do not use GitHub CLI (`gh`) in this repository workflow. - Create a Gitea issue before any code or documentation change. - Work on a feature branch `feature/issue-{N}-{short-description}` and open a PR. - Never commit directly to `main`. @@ -43,3 +45,8 @@ It is distinct from `docs/requirements-log.md`, which records **project/product - When work requires guidance, consult the relevant `docs/` policies first. - Any code change must be accompanied by relevant documentation updates. - Persist user constraints across sessions by recording them in this document. + +### 2026-02-27 + +- All agents must pre-read `docs/commands.md` and `docs/workflow.md` troubleshooting before running Gitea issue/PR/comment commands. +- `gh` CLI is prohibited for repository ticket/PR operations; use `tea` (or documented Gitea API fallback only). diff --git a/docs/commands.md b/docs/commands.md index b72df71..666c0b3 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -4,6 +4,13 @@ **Critical: Learn from failures. Never repeat the same failed command without modification.** +## Repository VCS Rule (Mandatory) + +- 이 저장소의 티켓/PR/코멘트 작업은 Gitea 기준으로 수행한다. +- `gh`(GitHub CLI) 명령 사용은 금지한다. +- 기본 도구는 `tea`이며, `tea` 미지원 케이스만 Gitea API를 fallback으로 사용한다. +- 실행 전 `docs/workflow.md`의 `Gitea CLI Formatting Troubleshooting`을 반드시 확인한다. + ### tea CLI (Gitea Command Line Tool) #### ❌ TTY Error - Interactive Confirmation Fails @@ -140,6 +147,12 @@ python -m src.main --mode=paper # Run with dashboard enabled python -m src.main --mode=paper --dashboard +# Runtime verification monitor (NOT_OBSERVED detection) +bash scripts/runtime_verify_monitor.sh + +# Follow runtime verification log +tail -f data/overnight/runtime_verify_*.log + # Docker docker compose up -d ouroboros # Run agent docker compose --profile test up test # Run tests in container diff --git a/docs/ouroboros/50_tpm_control_protocol.md b/docs/ouroboros/50_tpm_control_protocol.md index ec52e6d..56de1f3 100644 --- a/docs/ouroboros/50_tpm_control_protocol.md +++ b/docs/ouroboros/50_tpm_control_protocol.md @@ -34,6 +34,12 @@ Main Agent 아이디에이션 책임: - DCP-03 구현 착수: Phase 2 종료 전 Main Agent 승인 필수 - DCP-04 배포 승인: Phase 4 종료 후 Main Agent 최종 승인 필수 +Main/Verifier 사고 재발 방지 규칙: +- Main Agent는 검증 위임 시 `Directive Contract`를 충족하지 않으면 검증 착수 금지 +- Verifier Agent는 지시 누락/모호성 발견 시 즉시 `BLOCKED`를 선언하고 보완 요청 +- Verifier Agent는 `미관측(NOT_OBSERVED)` 항목을 PASS로 보고할 수 없다 +- Runtime 검증에서 요구 세션 증적이 없으면 "정상"이 아니라 `미검증 이상`으로 이슈화한다 + ## Phase Control Gates ### Phase 0: Scenario Intake and Scope Lock @@ -112,6 +118,8 @@ Exit criteria: Control checks: - Verifier가 테스트 증적(로그/리포트/실행 커맨드) 첨부 +- Verifier가 `Coverage Matrix`(`REQ/TASK/TEST` x `PASS/FAIL/NOT_OBSERVED`) 첨부 +- `NOT_OBSERVED` 항목 수가 0인지 확인(0이 아니면 Gate 실패) - Runtime Verifier가 스테이징/실운영 모니터링 계획 승인 - 산출물: 수용 승인 레코드 @@ -150,6 +158,8 @@ TPM 티켓 운영 규칙: - PR 본문에는 TPM이 지정한 우선순위와 범위가 그대로 반영되어야 한다. - 우선순위 변경은 TPM 제안 + Main Agent 승인으로만 가능하다. - PM/TPM/Dev/Reviewer/Verifier/Runtime Verifier는 주요 의사결정 시점마다 PR 코멘트를 남겨 결정 근거를 추적 가능 상태로 유지한다. +- PM/TPM/Dev/Reviewer/Verifier/Runtime Verifier는 이슈/PR/코멘트 조작 전에 `docs/commands.md`와 `docs/workflow.md`의 Gitea 트러블슈팅 섹션을 선참조해야 한다. +- 저장소 협업에서 GitHub CLI(`gh`) 사용은 금지하며, Gitea 작업은 `tea`(필요 시 문서화된 API fallback)만 허용한다. 브랜치 운영 규칙: - TPM은 각 티켓에 대해 `ticket temp branch -> program feature branch` PR 경로를 지정한다. @@ -168,6 +178,8 @@ TPM 티켓 운영 규칙: - 시스템 실제 구동(스테이징/로컬 실운영 모드) 실행 - 모니터링 체크리스트(핵심 경보/주문 경로/예외 로그) 수행 - 결과를 티켓/PR 코멘트에 증적으로 첨부하지 않으면 완료로 간주하지 않음 + - 세션별 필수 관측 포인트(`NXT`, `US_PRE`, `US_DAY`, `US_AFTER` 등) 중 미관측 항목은 `NOT_OBSERVED`로 기록 + - `NOT_OBSERVED` 존재 시 승인 금지 + Runtime 이슈 발행 ## Server Reflection Rule diff --git a/docs/ouroboros/60_repo_enforcement_checklist.md b/docs/ouroboros/60_repo_enforcement_checklist.md index 2573aea..b1100f3 100644 --- a/docs/ouroboros/60_repo_enforcement_checklist.md +++ b/docs/ouroboros/60_repo_enforcement_checklist.md @@ -48,6 +48,7 @@ Updated: 2026-02-26 병합 전 체크리스트: - 이슈 연결(`Closes #N`) 존재 - PR 본문에 `REQ-*`, `TASK-*`, `TEST-*` 매핑 표 존재 +- Main -> Verifier Directive Contract(범위/방법/합격/실패/미관측/증적 형식) 기재 - `src/core/risk_manager.py` 변경 없음 - 주요 의사결정 체크포인트(DCP-01~04) 중 해당 단계 Main Agent 확인 기록 존재 - 주요 의사결정(리뷰 지적/수정 합의/검증 승인)에 대한 에이전트 PR 코멘트 존재 @@ -57,6 +58,10 @@ Updated: 2026-02-26 - 문서 검증 스크립트 통과 - 테스트 통과 - 개발 완료 시 시스템 구동/모니터링 증적 코멘트 존재 +- 이슈/PR 조작 전에 `docs/commands.md` 및 `docs/workflow.md` 트러블슈팅 확인 코멘트 존재 +- `gh` CLI 미사용, `tea` 사용 증적 존재 +- Verifier `Coverage Matrix` 첨부(PASS/FAIL/NOT_OBSERVED) +- `NOT_OBSERVED` 항목 0 확인(0이 아니면 머지 금지) ## 5) 감사 추적 diff --git a/docs/workflow.md b/docs/workflow.md index 814fe8c..0a24ac9 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -16,6 +16,20 @@ **Never commit directly to `main`.** This policy applies to all changes, no exceptions. +## Agent Gitea Preflight (Mandatory) + +Gitea 이슈/PR/코멘트 작업 전에 모든 에이전트는 아래를 먼저 확인해야 한다. + +1. `docs/commands.md`의 `tea CLI` 실패 사례/해결 패턴 확인 +2. 본 문서의 `Gitea CLI Formatting Troubleshooting` 확인 +3. 명령 실행 전 `gh`(GitHub CLI) 사용 금지 확인 + +강제 규칙: +- 이 저장소 협업 명령은 `tea`를 기본으로 사용한다. +- `gh issue`, `gh pr` 등 GitHub CLI 명령은 사용 금지다. +- `tea` 실패 시 동일 명령 재시도 전에 원인/수정사항을 PR 코멘트에 남긴다. +- 필요한 경우에만 Gitea API(`localhost:3000`)를 fallback으로 사용한다. + ## Branch Strategy (Mandatory) - Team operation default branch is the **program feature branch**, not `main`. @@ -137,6 +151,22 @@ task_tool( Use `run_in_background=True` for independent tasks that don't block subsequent work. +### Main -> Verifier Directive Contract (Mandatory) + +메인 에이전트가 검증 에이전트에 작업을 위임할 때, 아래 6개를 누락하면 지시가 무효다. + +1. 검증 대상 범위: `REQ-*`, `TASK-*`, 코드/로그 경로 +2. 검증 방법: 실행 커맨드와 관측 포인트(예: 세션별 로그 키워드) +3. 합격 기준: PASS 조건을 수치/문구로 명시 +4. 실패 기준: FAIL 조건을 수치/문구로 명시 +5. 미관측 기준: `NOT_OBSERVED` 조건과 즉시 에스컬레이션 규칙 +6. 증적 형식: PR 코멘트에 `Coverage Matrix` 표로 제출 + +`NOT_OBSERVED` 처리 규칙: +- 요구사항 항목이 관측되지 않았으면 PASS로 간주 금지 +- `NOT_OBSERVED`는 운영상 `FAIL`과 동일하게 처리 +- `NOT_OBSERVED`가 하나라도 있으면 승인/머지 금지 + ## Code Review Checklist **CRITICAL: Every PR review MUST verify plan-implementation consistency.** @@ -170,3 +200,7 @@ Before approving any PR, the reviewer (human or agent) must check ALL of the fol - [ ] PR references the Gitea issue number - [ ] Feature branch follows naming convention (`feature/issue-N-description`) - [ ] Commit messages are clear and descriptive +- [ ] 이슈/PR 작업 전에 `docs/commands.md`와 본 문서 트러블슈팅 섹션을 확인했다 +- [ ] `gh` 명령을 사용하지 않고 `tea`(또는 허용된 Gitea API fallback)만 사용했다 +- [ ] Main -> Verifier 지시가 Directive Contract 6개 항목을 모두 포함한다 +- [ ] Verifier 결과에 `Coverage Matrix`(PASS/FAIL/NOT_OBSERVED)가 있고, `NOT_OBSERVED=0`이다 diff --git a/scripts/runtime_verify_monitor.sh b/scripts/runtime_verify_monitor.sh new file mode 100755 index 0000000..6c878a4 --- /dev/null +++ b/scripts/runtime_verify_monitor.sh @@ -0,0 +1,78 @@ +#!/usr/bin/env bash +# Runtime verification monitor with NOT_OBSERVED detection. + +set -euo pipefail + +ROOT_DIR="${ROOT_DIR:-/home/agentson/repos/The-Ouroboros}" +LOG_DIR="${LOG_DIR:-$ROOT_DIR/data/overnight}" +INTERVAL_SEC="${INTERVAL_SEC:-60}" +MAX_HOURS="${MAX_HOURS:-24}" + +cd "$ROOT_DIR" + +OUT_LOG="$LOG_DIR/runtime_verify_$(date +%Y%m%d_%H%M%S).log" +END_TS=$(( $(date +%s) + MAX_HOURS*3600 )) + +log() { + printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$1" | tee -a "$OUT_LOG" >/dev/null +} + +check_signal() { + local name="$1" + local pattern="$2" + local run_log="$3" + + if rg -q "$pattern" "$run_log"; then + log "[COVERAGE] ${name}=PASS pattern=${pattern}" + return 0 + fi + log "[COVERAGE] ${name}=NOT_OBSERVED pattern=${pattern}" + return 1 +} + +log "[INFO] runtime verify monitor started interval=${INTERVAL_SEC}s max_hours=${MAX_HOURS}" + +while true; do + now=$(date +%s) + if [ "$now" -ge "$END_TS" ]; then + log "[INFO] monitor completed (time window reached)" + exit 0 + fi + + latest_run="$(ls -t "$LOG_DIR"/run_*.log 2>/dev/null | head -n1 || true)" + if [ -z "$latest_run" ]; then + log "[ANOMALY] no run log found" + sleep "$INTERVAL_SEC" + continue + fi + + # Basic liveness hints. + app_pid="$(cat "$LOG_DIR/app.pid" 2>/dev/null || true)" + wd_pid="$(cat "$LOG_DIR/watchdog.pid" 2>/dev/null || true)" + app_alive=0 + wd_alive=0 + port_alive=0 + [ -n "$app_pid" ] && kill -0 "$app_pid" 2>/dev/null && app_alive=1 + [ -n "$wd_pid" ] && kill -0 "$wd_pid" 2>/dev/null && wd_alive=1 + ss -ltnp 2>/dev/null | rg -q ':8080' && port_alive=1 + log "[HEARTBEAT] run_log=$latest_run app_alive=$app_alive watchdog_alive=$wd_alive port8080=$port_alive" + + # Coverage matrix rows (session paths and policy gate evidence). + not_observed=0 + check_signal "LIVE_MODE" "Mode: live" "$latest_run" || not_observed=$((not_observed+1)) + check_signal "KR_LOOP" "Processing market: Korea Exchange" "$latest_run" || not_observed=$((not_observed+1)) + check_signal "NXT_PATH" "NXT_PRE|NXT_AFTER|session=NXT_" "$latest_run" || not_observed=$((not_observed+1)) + check_signal "US_PRE_PATH" "US_PRE|session=US_PRE" "$latest_run" || not_observed=$((not_observed+1)) + check_signal "US_DAY_PATH" "US_DAY|session=US_DAY|Processing market: .*NASDAQ|Processing market: .*NYSE|Processing market: .*AMEX" "$latest_run" || not_observed=$((not_observed+1)) + check_signal "US_AFTER_PATH" "US_AFTER|session=US_AFTER" "$latest_run" || not_observed=$((not_observed+1)) + check_signal "ORDER_POLICY_SESSION" "Order policy rejected .*\\[session=" "$latest_run" || not_observed=$((not_observed+1)) + + if [ "$not_observed" -gt 0 ]; then + log "[ANOMALY] coverage_not_observed=$not_observed (treat as FAIL)" + else + log "[OK] coverage complete (NOT_OBSERVED=0)" + fi + + sleep "$INTERVAL_SEC" +done + diff --git a/scripts/validate_governance_assets.py b/scripts/validate_governance_assets.py new file mode 100644 index 0000000..e7058a2 --- /dev/null +++ b/scripts/validate_governance_assets.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +"""Validate persistent governance assets for agent workflow safety.""" + +from __future__ import annotations + +import sys +from pathlib import Path + + +def must_contain(path: Path, required: list[str], errors: list[str]) -> None: + if not path.exists(): + errors.append(f"missing file: {path}") + return + text = path.read_text(encoding="utf-8") + for token in required: + if token not in text: + errors.append(f"{path}: missing required token -> {token}") + + +def main() -> int: + errors: list[str] = [] + + pr_template = Path(".gitea/PULL_REQUEST_TEMPLATE.md") + issue_template = Path(".gitea/ISSUE_TEMPLATE/runtime_verification.md") + + must_contain( + pr_template, + [ + "Closes #N", + "Main -> Verifier Directive Contract", + "Coverage Matrix", + "NOT_OBSERVED", + "tea", + "gh", + ], + errors, + ) + must_contain( + issue_template, + [ + "[RUNTIME-VERIFY][SCN-XXX]", + "Requirement Mapping", + "Close Criteria", + "NOT_OBSERVED = 0", + ], + errors, + ) + + if errors: + print("[FAIL] governance asset validation failed") + for err in errors: + print(f"- {err}") + return 1 + + print("[OK] governance assets validated") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) +