From e0ba3711ece6d5e5d3b4d8e236f0a82e7d6d8058 Mon Sep 17 00:00:00 2001 From: toki Date: Wed, 24 Jun 2026 23:12:06 +0900 Subject: [PATCH] sync: pull from agentic-framework v1.1.156 --- agent-ops/.version | 2 +- .../_templates/test-env-rules-template.md | 19 ++++++++++++------- agent-ops/rules/common/philosophy.md | 2 +- .../skills/common/agent-contract/SKILL.md | 2 +- agent-ops/skills/common/create-test/SKILL.md | 5 +++-- agent-ops/skills/common/plan/SKILL.md | 16 +++++++++------- 6 files changed, 27 insertions(+), 19 deletions(-) diff --git a/agent-ops/.version b/agent-ops/.version index a10b76e..a0090b5 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.153 +1.1.156 diff --git a/agent-ops/rules/common/_templates/test-env-rules-template.md b/agent-ops/rules/common/_templates/test-env-rules-template.md index 66cca94..c336d32 100644 --- a/agent-ops/rules/common/_templates/test-env-rules-template.md +++ b/agent-ops/rules/common/_templates/test-env-rules-template.md @@ -1,15 +1,15 @@ --- -test_env: +test_env: last_rule_updated_at: --- -# 테스트 규칙 +# 테스트 규칙 **현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.** ## 공통 규칙 -- 테스트/검증은 이 파일을 기준으로 판단한다. +- 테스트/검증은 이 파일을 기준으로 판단한다. - 작업 완료 검증은 변경 범위 기준으로 선택한다. - 필수 검증을 실행하지 못하면 차단 사유로 보고한다. - 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다. @@ -18,17 +18,22 @@ last_rule_updated_at: ## 기본 환경 - host: -- port: +- repo root: +- sync 기준: - runtime: - package manager: -- docker: - external service: -- model endpoint: - credential: +## 프리플라이트 + +- plan 작성 시 필수 검증이 현재 checkout을 벗어나 원격 runner, 외부 서비스, Docker/code-server, emulator/device, 공유 장기 runtime을 사용하면 먼저 테스트 환경 프리플라이트를 계획에 기록한다. +- 테스트 환경 프리플라이트에는 runner, repo root/workdir, branch/HEAD/dirty 상태, local 변경과 원격 source 동기화 여부, binary/artifact 경로와 필요한 help/version 출력, config path, runtime identity, port/process 상태, 외부 host, OS/arch 가정을 포함한다. +- 프리플라이트에서 dirty/divergent checkout, stale artifact, 잘못된 identity, missing command, closed port, host OS 불일치, source 미동기화가 확인되면 plan은 먼저 setup/sync/rebuild 단계를 만들거나 blocker로 보고한다. + ## 라우팅 -- / / : `agent-test//.md` +- / / : `agent-test//.md` ## 라우팅 규칙 diff --git a/agent-ops/rules/common/philosophy.md b/agent-ops/rules/common/philosophy.md index b1b41f7..f7273c5 100644 --- a/agent-ops/rules/common/philosophy.md +++ b/agent-ops/rules/common/philosophy.md @@ -53,7 +53,7 @@ - 그룹 간 연결은 사용자 명령, 런타임 이벤트, 또는 판별 가능한 파일 상태로만 한다. - 구현 작업 그룹은 `plan`과 `code-review`의 PLAN/CODE_REVIEW 루프를 소유한다. - 로드맵 그룹은 `create-roadmap`과 `update-roadmap`의 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신 흐름을 소유한다. -- Phase/Milestone 상태 전환, 구현 잠금 동기화, archive 이동, 완료 이벤트 반영처럼 결정적으로 판별 가능한 action은 NomadCode Core 또는 런타임이 있으면 그쪽 책임으로 둔다. +- Phase/Milestone 상태 전환, 구현 잠금 동기화, archive 이동, 완료 이벤트 반영처럼 결정적으로 판별 가능한 action은 Core/MCP 또는 런타임이 있으면 그쪽 책임으로 둔다. - `code-review`가 남긴 PASS 완료 이벤트를 로드맵에 반영할지, 언제 반영할지는 런타임이 판단하고 Core/MCP action이 있으면 그쪽으로, 없으면 `update-roadmap` file-based fallback 흐름으로 넘긴다. - cross-project 잠금이나 `.agent-roadmap-sync` 같은 workspace-level 상태는 로드맵 그룹, Core, 런타임의 공동 경계다. `plan`과 `code-review`에 의존성 동기화 규칙을 넣지 않는다. - 새 스킬을 만들기 전에 기존 그룹의 자연스러운 입력, 상태 전환, 후처리 지점에 넣을 수 있는지 먼저 본다. 다만 다른 그룹 경계를 침범해야 하면 런타임 이벤트로 분리한다. diff --git a/agent-ops/skills/common/agent-contract/SKILL.md b/agent-ops/skills/common/agent-contract/SKILL.md index b254647..82a8bbd 100644 --- a/agent-ops/skills/common/agent-contract/SKILL.md +++ b/agent-ops/skills/common/agent-contract/SKILL.md @@ -20,7 +20,7 @@ description: agent-contract index와 제공/소비 계약 문서를 생성하거 ## 입력 -- `contract-id`: 계약 식별자, 예: `iop.openai-compatible-api` (필수) +- `contract-id`: 계약 식별자, 예: `billing.public-api` 또는 `auth.session-events` (필수) - `mode`: `provided` 또는 `consumed` (필수) - `contract-path`: 계약 원문 경로 또는 외부 source 경로 (필수) - `trigger-conditions`: 계약 문서를 읽어야 하는 조건 목록 (필수) diff --git a/agent-ops/skills/common/create-test/SKILL.md b/agent-ops/skills/common/create-test/SKILL.md index a9ceee9..7563bb5 100644 --- a/agent-ops/skills/common/create-test/SKILL.md +++ b/agent-ops/skills/common/create-test/SKILL.md @@ -49,6 +49,7 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테 - [ ] 테스트 명령 확인을 위해 프로젝트의 대표 설정 파일을 가볍게 확인한다. 예: `package.json`, `Makefile`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `docker-compose*.yml`, `.github/workflows/**`. - [ ] `agent-ops/rules/common/_templates/test-env-rules-template.md`를 읽는다. - [ ] `agent-ops/rules/common/_templates/test-case-rule-template.md`를 읽는다. +- [ ] 프로젝트에 `agent-test/_templates/env-rules-template.md` 또는 `agent-test/_templates/test-profile-template.md`가 있으면 해당 프로젝트 템플릿을 공통 템플릿보다 우선한다. - [ ] `agent-test//rules.md` 존재 여부를 확인한다. - [ ] `agent-test//rules.md`가 있으면 읽고 missing / blank-skeleton / structured-incomplete / usable 중 하나로 분류한다. - [ ] 도메인 baseline과 추가 생성 대상 `agent-test//*.md`의 존재 여부를 확인하고, 있으면 blank-skeleton / structured-incomplete / usable 중 하나로 분류한다. @@ -56,7 +57,7 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테 ## 실행 절차 1. **환경 rules 생성** - - `agent-test//rules.md`가 없으면 `test-env-rules-template.md` 형식으로 만든다. + - `agent-test//rules.md`가 없으면 프로젝트 `agent-test/_templates/env-rules-template.md`가 있을 때는 그 형식으로 만들고, 없으면 공통 `test-env-rules-template.md` 형식으로 만든다. - `agent-test//rules.md`가 구조적 blank/skeleton이면 기존 구체 값을 보존한 채 빠진 frontmatter, 정독 필수 문구, 필수 섹션, baseline 라우팅 영역만 보완한다. - usable한 기존 env rules는 덮어쓰지 않고 라우팅 추가가 필요한 경우에만 최소 수정한다. - 제목은 `# 테스트 규칙`으로 쓴다. @@ -74,7 +75,7 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테 - 도메인은 새로 발명하지 않는다. 도메인 매핑이나 domain rule에서 확인되지 않은 이름은 `project-wide`로 기록한다. 3. **도메인/검증 시나리오별 문서 생성** - - 생성 대상 문서가 없으면 `agent-test//.md`를 `test-case-rule-template.md` 형식으로 만든다. + - 생성 대상 문서가 없으면 프로젝트 `agent-test/_templates/test-profile-template.md`가 있을 때는 그 형식으로 만들고, 없으면 공통 `test-case-rule-template.md` 형식으로 만든다. - 대상 문서가 이미 있고 usable하면 덮어쓰지 않는다. - 대상 문서가 구조적 blank/skeleton이면 기존 구체 값을 보존한 채 빠진 frontmatter와 필수 섹션을 보완한다. - frontmatter에는 `test_profile`, `domain`, `verification_type`, `last_rule_updated_at`을 채운다. diff --git a/agent-ops/skills/common/plan/SKILL.md b/agent-ops/skills/common/plan/SKILL.md index 3d637d7..3f705e7 100644 --- a/agent-ops/skills/common/plan/SKILL.md +++ b/agent-ops/skills/common/plan/SKILL.md @@ -175,12 +175,13 @@ Before choosing plan files or task directory names, apply the split decision pol ## Step 2 - Analyze Before Writing -Complete all items below before creating active plan/review files. Work through them in order; do not proceed to the next step until every checkbox is done. The only allowed file edits before writing plan/review files are local `agent-roadmap/current.md` creation or `.gitignore` block repair needed for roadmap routing, plus `create-test` or `update-test` edits needed to make test rules usable for this plan. +Complete all items below before creating active plan/review files. Work through them in order; do not proceed to the next step until every checkbox is done. The only allowed file edits before writing plan/review files are local `agent-roadmap/current.md` creation or `.gitignore` block repair needed for roadmap routing, plus `create-test` or `update-test` edits when the repository already uses agent-test for the relevant scope or the user explicitly asked to maintain test rules. -- [ ] **Load test environment rules** — because implementation plans include verification, determine `test_env` before choosing verification commands. Use the user-specified environment when provided; otherwise use `local`. Check `agent-test//rules.md` and read it in full when present, even if it appears blank or skeleton. If it is absent, or present but structurally blank/skeleton, invoke `create-test` with `env=` when this repo can be edited, then re-read the generated or completed rules before writing the plan. If creation is not possible in the current task context, record the gap and fallback source; absence is not a user-review blocker by itself. +- [ ] **Load test environment rules** — because implementation plans include verification, determine `test_env` before choosing verification commands. Use the user-specified environment when provided; otherwise use `local`. Agent-test is optional: some repositories or tasks intentionally do not have or use `agent-test/`. Check `agent-test//rules.md`; read it in full when present, even if it appears blank or skeleton. If it is absent, record that no agent-test rule was applied and choose fallback verification sources from repository manifests, scripts, workflows, domain rules, or direct read-only environment probes. Do not create agent-test files merely because a plan has verification. Invoke `create-test` only when the user asked for test-rule creation/maintenance, the current task is itself test-rule work, or the repository already uses agent-test for this scope and the missing/blank rule is a real maintenance gap. If creation is not appropriate or possible in the current task context, record the gap and fallback source; absence is not a user-review blocker by itself. - [ ] **Read all source files in full** — read every source file the change will touch, whole file. No partial reads. -- [ ] **Resolve test profiles** — from the env rules `## 라우팅`, read every matching `agent-test//.md` in full. Use `create-test` for missing or structurally blank routes/profiles when the current task can safely fill the gap. Use `update-test` only when verified command or criteria facts are available or the user asked to maintain test rules. If a profile exists but leaves command/criteria values as `<확인 필요>`, record the incomplete values and choose fallback verification commands from repository manifests or workflows with lower confidence. Do not claim agent-test requires a command that is not written in the env rules or matched profiles. -- [ ] **Read all test files in full** — read every test file that exercises the changed behavior, including files implied by the matched agent-test profiles and repository test layout. +- [ ] **Resolve test profiles** — if env rules exist and contain `## 라우팅`, read every matching `agent-test//.md` in full. If agent-test is absent or intentionally unused for the task, skip profile resolution and record the fallback verification source. Use `create-test` for missing or structurally blank routes/profiles only when the repository already uses agent-test for this scope or the task is test-rule maintenance. Use `update-test` only when verified command or criteria facts are available or the user asked to maintain test rules. If a profile exists but leaves command/criteria values as `<확인 필요>`, record the incomplete values and choose fallback verification commands from repository manifests or workflows with lower confidence. Do not claim agent-test requires a command that is not written in the env rules or matched profiles. +- [ ] **Preflight non-local test environments** — when any required verification leaves the current checkout, including remote runner, field/bootstrap, external provider, Docker/code-server, emulator/device, or shared long-running runtime, derive a read-only preflight before writing final verification commands. Use matched `agent-test` rules when they exist and apply; otherwise derive the preflight from repository manifests, scripts, workflows, domain rules, current task evidence, user-provided environment facts, and direct read-only probes. Record runner, repo root/workdir, branch/HEAD/dirty state, source sync status, binary/artifact paths, command help/version output needed by the verification, config path, runtime identity such as Edge id, ports/process state, external hosts, and OS/arch assumptions. If the preflight shows stale artifacts, dirty/divergent checkout, wrong identity, missing command, closed ports, host OS mismatch, or unsynced source, the plan must add an explicit setup/sync/rebuild step or report the blocker; do not write verification commands that silently assume profile or fallback values are already true. +- [ ] **Read all test files in full** — read every test file that exercises the changed behavior, including files implied by matched agent-test profiles when any are used and by the repository test layout. - [ ] **Assess test coverage** — for each behavior change, explicitly record whether existing tests cover it. - [ ] **Assess split boundaries first** — identify dependency boundaries, ownership boundaries, API-vs-call-site phases, test strategy splits, risk profile splits, and independently verifiable subwork before selecting plan files. If any split gate applies or the decision is uncertain, write multiple subtask directories under one task group instead of one plan. - [ ] **Resolve split predecessor completion** — if the selected or proposed subtask directory has `NN+PP[,QQ...]_...`, resolve each predecessor index under the same task group. Check only the active and archive candidate patterns defined in the task directory naming rules. Record found active/archive paths, missing predecessors, or ambiguous matches in `분석 결과 > 분할 판단` and, when order matters, `의존 관계 및 구현 순서`. @@ -237,9 +238,9 @@ Required sections: - Completion mode: check-on-pass ``` - `분석 결과`: record the findings from Step 2 and Step 3. This section is the written output of the analysis — not a summary, but the actual findings that justify the plan's scope and decisions. Must include all of the following subsections: - - `읽은 파일`: list every source, test, and agent-test rule/profile file read during analysis, with path. + - `읽은 파일`: list every source and test file read during analysis, with path. List agent-test rule/profile files only when they were actually present and read. - `SDD 기준`: for `SDD: 필요` Milestones, list the SDD path, status, targeted Acceptance Scenario ids, their Milestone Task ids, and the Evidence Map rows that drive the plan. State explicitly how those rows shaped the implementation checklist and final verification. If the selected Milestone has `SDD: 불필요`, state the recorded reason. If the work is not Milestone-linked, state "not applicable". - - `테스트 환경 규칙`: state the chosen `test_env`, whether `agent-test//rules.md` was present and read, every matched profile path read, the concrete rules/commands applied, any structural blank/skeleton or missing rules, any `<확인 필요>` values, and any fallback verification source. If agent-test is absent or unusable, explicitly say no agent-test rule was applied and whether `create-test` or `update-test` should later fill the gap. + - `테스트 환경 규칙`: state the chosen `test_env`, whether `agent-test//rules.md` was present/read/missing/intentionally unused, every matched profile path read when any, the concrete rules/commands applied, any structural blank/skeleton or missing rules, any `<확인 필요>` values, and any fallback verification source. If any required verification leaves the current checkout, include a `테스트 환경 프리플라이트` record with runner, repo root/workdir, branch/HEAD/dirty state, source sync status, binary/artifact paths, required command help/version output, config path, runtime identity such as Edge id, ports/process state, external hosts, OS/arch assumptions, and the exact setup/sync/rebuild step or blocker derived from mismatches. If agent-test is absent or unusable, explicitly say no agent-test rule was applied, what fallback is used, and whether test-rule maintenance is actually needed or not needed for this task. - `테스트 커버리지 공백`: list each behavior change and whether existing tests cover it; explicitly note gaps. - `심볼 참조`: list renamed/removed symbols and every call site found, or state "none" if no symbols were changed. - `분할 판단`: state that the split decision policy was evaluated before choosing plan files. For a single plan, explain why each relevant split gate does not apply and why single-plan coordination is safer than splitting. For multi-plan output, list the shared task group plus each sibling subtask directory and dependency relationship. For dependent subtask plans, include each predecessor index and whether it is satisfied by an active or archived `complete.log`, missing, or ambiguous. @@ -287,6 +288,7 @@ Verification fidelity rules: - Plan verification commands are a contract. The implementing agent must run them exactly as written. - If a command must be changed, the implementing agent must record the replacement command and reason in `계획 대비 변경 사항`, then paste the replacement command's actual stdout/stderr. - Before claiming a tool is unavailable, run and record `command -v ` or the project-equivalent check. +- Before a remote/field/external verification command assumes a checkout, binary, config, runtime identity, or listening port, the plan must include a preflight command that proves those assumptions or a setup command that makes them true. - Do not download, generate, or leave verification tools inside the repository. Temporary tools belong outside the repo, such as under `/tmp`, and must not become task artifacts. - For search commands whose output order may vary, specify deterministic options in the plan, for example `rg --sort path`. - `검증 결과` must contain actual stdout/stderr, not summarized or reconstructed output. If output is too long, record the saved output file path and the exact command used to create it. @@ -459,7 +461,7 @@ Sections and their ownership: - If `Roadmap Targets` exists in the plan, the review stub contains the identical section. If it does not exist in the plan, the review stub omits it too. - If the selected Milestone has `SDD: 필요`, the plan's `분석 결과 > SDD 기준` proves that the implementation checklist and final verification were derived from the approved SDD Acceptance Scenarios and Evidence Map. Missing SDD mapping blocks plan creation. - If the plan is a follow-up or resumes from prior archive evidence, it has `Archive Evidence Snapshot` and the review stub contains the identical section. -- `분석 결과 > 테스트 환경 규칙` records the selected test env, env rules read/missing/structural-blank state, matched profiles read, and any fallback verification source. +- `분석 결과 > 테스트 환경 규칙` records the selected test env, env rules read/missing/structural-blank/intentionally-unused state, matched profiles read when any, and any fallback verification source. - Dependent split plans record predecessor completion using active sibling `complete.log` or matching archived `complete.log`; ambiguous archive matches are not guessed. - Every plan item has problem, solution, checklist, test decision, and intermediate verification. - The plan and review stub have matching `구현 체크리스트` item text/order, and the final checkbox is the mandatory `CODE_REVIEW-*-G??.md` completion item.