ai-ops-cli 1.3.1 → 1.4.1

package/README.ko.md

@@ -102,6 +102,7 @@ Commands:
   skill      Manage skill components
   subagent   Manage subagent components
   pack       Manage optional project operating layer packs
+  studio    Generate read-only Studio snapshot contracts
   integration Manage user/global runtime integrations
   context-promotion Manage context promotion review receipts
   codex-hook Manage Codex hook components
@@ -109,6 +110,14 @@ Commands:
 
 `--tool`은 유지합니다. Codex, Claude Code, Gemini CLI가 서로 다른 discovery 위치와 adapter 파일을 사용하기 때문입니다.
 
+Studio read-only snapshot 명령:
+
+```bash
+ai-ops studio snapshot --json
+```
+
+이 명령은 ai-ops Studio가 소비할 JSON contract를 출력합니다. Desktop app을 실행하거나 project/runtime 파일을 수정하지 않고 project context layer, audit 상태, user/global runtime 상태만 읽습니다.
+
 Integration lifecycle 명령:
 
 ```bash
@@ -153,8 +162,33 @@ ai-ops codex-hook install context-promotion
 ai-ops codex-hook install context-promotion --command "/custom/bin/ai-ops context-promotion hook post-tool-use"
 ai-ops codex-hook status context-promotion
 ai-ops codex-hook uninstall context-promotion
+ai-ops codex-permissions install safe-local
+ai-ops codex-permissions status safe-local
+ai-ops codex-permissions uninstall safe-local
 ```
 
+`safe-local`은 `~/.codex/config.toml`에 `ai-ops-safe-local` user-level Codex permission profile을 관리합니다. `~/.personal-project-contexts`, `${AI_OPS_HOME:-$HOME}/.ai-ops/context-promotion`, active workspace root 아래 `.codex/plans`에는 write를 허용하고, `.git`은 read-only로 두며 `**/*.env`는 deny합니다. `PermissionRequest` hook이나 command allow rule은 설치하지 않습니다.
+
+ai-coding worker에서는 Codex subprocess를 run-scoped로 실행하고, commit/push/PR 생성은 orchestrator가 담당하게 합니다.
+
+```bash
+codex exec --ignore-user-config --ignore-rules --cd "$WORKTREE" \
+  -c 'approval_policy="never"' \
+  -c 'default_permissions=":read-only"'
+
+codex exec --ignore-user-config --ignore-rules --cd "$WORKTREE" \
+  -c 'approval_policy="never"' \
+  -c 'default_permissions="ai-worker-impl"' \
+  -c 'permissions.ai-worker-impl.filesystem.":minimal"="read"' \
+  -c 'permissions.ai-worker-impl.filesystem.":workspace_roots"."."="write"' \
+  -c 'permissions.ai-worker-impl.filesystem.":workspace_roots".".git"="read"' \
+  -c 'permissions.ai-worker-impl.filesystem.":workspace_roots".".codex/plans"="write"' \
+  -c 'permissions.ai-worker-impl.filesystem.":workspace_roots"."**/*.env"="deny"' \
+  -c 'permissions.ai-worker-impl.network.enabled=false'
+```
+
+각 Codex 실행 후 orchestrator가 HEAD, branch ref, changed-file scope를 검증해야 합니다. Validation command 실행, commit 생성, branch push, `gh pr create --draft` 호출은 Codex가 아니라 orchestrator가 수행합니다.
+
 Subagent lifecycle 명령:
 
 ```bash

package/README.md

@@ -102,6 +102,7 @@ Commands:
   skill      Manage skill components
   subagent   Manage subagent components
   pack       Manage optional project operating layer packs
+  studio    Generate read-only Studio snapshot contracts
   integration Manage user/global runtime integrations
   context-promotion Manage context promotion review receipts
   codex-hook Manage Codex hook components
@@ -109,6 +110,14 @@ Commands:
 
 `--tool` remains because Codex, Claude Code, and Gemini CLI use different discovery locations and adapter files.
 
+Studio read-only snapshot command:
+
+```bash
+ai-ops studio snapshot --json
+```
+
+This emits the JSON contract consumed by ai-ops Studio. It reads the project context layer, audit state, and user/global runtime status without launching the desktop app or mutating project/runtime files.
+
 Integration lifecycle commands:
 
 ```bash
@@ -153,8 +162,33 @@ ai-ops codex-hook install context-promotion
 ai-ops codex-hook install context-promotion --command "/custom/bin/ai-ops context-promotion hook post-tool-use"
 ai-ops codex-hook status context-promotion
 ai-ops codex-hook uninstall context-promotion
+ai-ops codex-permissions install safe-local
+ai-ops codex-permissions status safe-local
+ai-ops codex-permissions uninstall safe-local
 ```
 
+`safe-local` manages a user-level Codex permission profile named `ai-ops-safe-local` in `~/.codex/config.toml`. It grants write access to `~/.personal-project-contexts`, `${AI_OPS_HOME:-$HOME}/.ai-ops/context-promotion`, and `.codex/plans` under active workspace roots while keeping `.git` read-only and denying `**/*.env`. It does not install `PermissionRequest` hooks or command allow rules.
+
+For an ai-coding worker, keep Codex subprocesses run-scoped and let the orchestrator own commits, pushes, and PR creation:
+
+```bash
+codex exec --ignore-user-config --ignore-rules --cd "$WORKTREE" \
+  -c 'approval_policy="never"' \
+  -c 'default_permissions=":read-only"'
+
+codex exec --ignore-user-config --ignore-rules --cd "$WORKTREE" \
+  -c 'approval_policy="never"' \
+  -c 'default_permissions="ai-worker-impl"' \
+  -c 'permissions.ai-worker-impl.filesystem.":minimal"="read"' \
+  -c 'permissions.ai-worker-impl.filesystem.":workspace_roots"."."="write"' \
+  -c 'permissions.ai-worker-impl.filesystem.":workspace_roots".".git"="read"' \
+  -c 'permissions.ai-worker-impl.filesystem.":workspace_roots".".codex/plans"="write"' \
+  -c 'permissions.ai-worker-impl.filesystem.":workspace_roots"."**/*.env"="deny"' \
+  -c 'permissions.ai-worker-impl.network.enabled=false'
+```
+
+After each Codex run, the orchestrator should verify HEAD, branch refs, and changed-file scope. The orchestrator, not Codex, should run validation commands, create commits, push branches, and call `gh pr create --draft`.
+
 Subagent lifecycle commands:
 
 ```bash

package/data/context-layer/docs/agent/checks/impact-checklist.md

@@ -16,3 +16,12 @@ update_when:
 - auth, permission, privacy, billing, credential, audit log에 영향이 있는가?
 - external integration, webhook, cron, queue, cache, background job에 영향이 있는가?
 - project-owned 문서, specs, runbook, operator guide, `docs/docs-status.md`, context-layer 갱신이 필요한가?
+
+## 유지보수 점검 신호
+
+다음 항목은 lint/test gate가 아니라 리팩토링 검토 신호다. 해당되면 변경을 끝내기 전에 분리, naming, test 위치를 한 번 확인한다.
+
+- touched production file이 250줄을 넘는가?
+- 새 기능을 400줄 이상 파일에 추가하는가?
+- 같은 패턴이 세 번째 등장했는가?
+- 한 변경이 서로 다른 책임의 section 3곳 이상을 건드리는가?

package/data/context-layer/docs/agent/rules/00-agent-baseline.md

@@ -7,6 +7,7 @@ read_when:
 update_when:
   - baseline_rule_changes
 ---
+
 # Agent Baseline Rules
 
 이 문서는 모든 작업 전에 먼저 적용할 기본 협업 규칙이다. 세부 routing, workflow, stop rule보다 앞서 읽고, 프로젝트별 Active 문서가 더 구체적인 판단 근거를 제공하면 그 문서를 우선한다.
@@ -34,6 +35,17 @@ update_when:
 - 파일 내부 선언은 types, constants, validators/guards, helper functions, main logic/exports 순서로 배치한다.
 - 한 파일에 의미가 다른 그룹이 둘 이상 있으면 `// ----- types -----` 같은 section divider comment로 경계를 표시한다.
 
+## 유지보수/리팩토링 기준
+
+- 줄 수 기준은 hard gate가 아니라 검토 신호로 사용한다. 자동 lint/test 실패 조건을 만들기보다 변경 맥락에서 분리 필요성을 판단한다.
+- touched production file이 250줄을 넘으면 책임 경계, 테스트 위치, helper 추출 가능성을 한 번 확인한다.
+- 새 기능을 400줄 이상 파일에 추가하려면 먼저 feature slice, command shell, pure logic, schema/state I/O로 나눌 수 있는지 검토한다.
+- production TypeScript 파일이 600줄을 넘으면 다음 기능 추가 전에 분리 계획을 우선 세운다.
+- 같은 패턴이 세 번째 등장하면 WET 유지보다 shared helper 또는 feature-local abstraction이 더 명확한지 확인한다.
+- 한 변경이 서로 다른 책임의 section 3곳 이상을 건드리면 파일/폴더 경계를 다시 그릴 시점으로 본다.
+- 공통화는 Rule of Three와 호출 맥락이 함께 맞을 때 진행한다. 우발적으로 비슷한 코드 두 개만 보고 abstraction을 만들지 않는다.
+- 리팩토링은 public CLI command, option, JSON/schema 계약을 보존하는 작은 이동부터 시작하고, behavior assertion은 먼저 유지한다.
+
 ## 네이밍
 
 - directory name은 kebab-case를 사용한다.
@@ -44,4 +56,4 @@ update_when:
 - flow, sequence, state, structure를 설명할 때 긴 bullet list보다 Mermaid diagram을 우선 검토한다.
 - UX/control flow와 decision tree는 `flowchart`, request/response와 service interaction은 `sequenceDiagram`, entity/schema relationship은 `erDiagram`, lifecycle/state transition은 `stateDiagram-v2`를 사용한다.
 - Mermaid diagram은 fenced `mermaid` code block으로 작성한다.
-- plan 문서를 저장할 때는 `YYYYMMDD_<topic>.md` 형식을 사용하고, topic은 kebab-case로 작성한다.
+- plan 문서를 저장할 때는 `YYYYMMDDHH_<topic>.md` 형식을 사용하고, topic은 kebab-case로 작성한다.

package/data/skills/task-skills/context-promotion-review/SKILL.md

@@ -5,56 +5,66 @@ description: 방금 완료된 작업 커밋에서 core, project-local, global로
 
 # context-promotion-review
 
-이 skill은 사용자가 명시적으로 호출했거나 `ai-ops` Codex PostToolUse hook이 작업 커밋 직후 후속 검토를 요청했을 때만 사용한다. CLI가 AI 판단을 하지 않으므로, 승격 후보 판정은 현재 Codex 대화 맥락과 방금 만든 `HEAD` 커밋을 바탕으로 이 skill에서 수행한다.
+이 skill은 사용자가 명시적으로 호출했거나 `ai-ops` Codex PostToolUse hook이 작업 커밋 직후 후속 검토를 요청했을 때만 사용한다. CLI가 AI 판단을 하지 않으므로, 승격 후보 판정은 현재 Codex 대화/리뷰 루프에서 반복되거나 사용자가 교정한 운영 판단과 방금 만든 `HEAD` 커밋을 바탕으로 이 skill에서 수행한다.
 
 hook이 전달한 Project root가 이 검토의 유일한 프로젝트 기준이다. 먼저 해당 Project root로 shell 기준을 맞추고, 다른 repo, parent directory, 이전 대화의 workspace, 웹 검색, 외부 문서를 사용하지 않는다. `AGENTS.md`, `docs/agent/*`, `docs/docs-status.md`, `.ai-ops/context-layer.json` 같은 context layer 파일이 없으면 없다고 보고하며 다른 repo 파일로 대체하지 않는다.
 
 ## 목적
 
-방금 완료된 작업 커밋에서 반복 가능한 운영 지식, 명령 루틴, 판단 기준이 생겼는지 확인하고, 사용자에게 승격 여부를 묻는다.
+방금 완료된 작업 커밋과 현재 대화/리뷰 루프에서 반복 가능한 운영 지식, 명령 루틴, 판단 기준이 생겼는지 확인하고, 사용자에게 승격 여부를 묻는다.
 
 검토 결과는 다음 다섯 가지로만 정리한다.
 
 - `core`: 모든 ai-ops 설치 프로젝트에 적용되어야 하는 제품 계약, CLI/Studio/schema/hook 동작
 - `project-local`: 현재 프로젝트에서만 반복 적용되는 agent rule, workflow, QA, business/spec 운영 기준
 - `global`: 여러 프로젝트에서 재사용할 skill, subagent, Codex hook 같은 runtime asset
-- `already-covered`: 이미 기존 context layer에 있는 기준이라 새 승격이 필요 없는 내용
+- `already-covered`: 기존 Active context layer에 같은 agent 행동 규칙이 있어 새 승격이 필요 없는 내용
 - `no-promotion`: 일회성 구현 세부사항, 임시 디버깅, 승격 가치가 없는 내용
 
 ## 절차
 
 1. hook 또는 사용자 요청에 표시된 Project root로 이동한다. Project root 밖 파일은 읽지 않는다.
 2. `ai-ops context-promotion status`를 실행해 현재 `HEAD`, fingerprint, receipt 상태를 확인한다.
-3. 방금 완료된 작업 커밋을 확인한다.
+3. 현재 post-commit worktree 상태를 확인한다.
+   - `git status --short`
+   - `git diff --name-only`
+   - `git diff --cached --name-only`
+   - `git ls-files --others --exclude-standard`
+4. 방금 완료된 작업 커밋을 확인한다.
    - `git show --stat HEAD`
    - `git show --name-only HEAD`
    - 필요 시 `git show HEAD`
-4. 기존 context layer를 cross-check한다.
+5. 기존 context layer를 cross-check한다.
    - `AGENTS.md`
    - `docs/docs-status.md`
    - `.ai-ops/context-layer.json`
    - `docs/agent/rules/*`
    - `docs/agent/checks/impact-checklist.md`
-5. context layer 파일이 없으면 absent로 기록하고, 다른 repo에서 대체 근거를 찾지 않는다.
-6. 이미 있는 규칙이면 `already-covered`로 보고하고 새 승격 후보로 만들지 않는다.
-7. 새 후보가 있으면 `core`, `project-local`, `global` 중 하나 이상으로 분류하고, 추천 위치를 제안한다.
-8. 후보가 없으면 `no-promotion` 결정을 제안한다.
-9. 사용자 승인 전에는 파일을 수정하지 않는다.
-10. 승인된 범위만 수정한다.
-11. 마지막에 반드시 `ai-ops context-promotion resolve ...`를 실행한다.
-12. 다시 `ai-ops context-promotion status`를 실행해 현재 `HEAD` receipt 확인을 한다.
-13. 승격 파일을 수정했더라도 직접 commit하지 않고 사용자 검사 대기 상태로 멈춘다.
+6. 현재 대화/리뷰 루프에서 반복되거나 사용자가 교정한 운영 판단을 확인한다.
+   - 사용자 교정, 반복 리뷰 지적, 새로 안정화한 명령 루틴을 후보로 본다.
+   - dirty worktree, untracked 파일, changeset pollution, staging scope 같은 커밋 hygiene 이슈가 반복되거나 교정되면 `project-local` 후보로 검토한다.
+7. context layer 파일이 없으면 absent로 기록하고, 다른 repo에서 대체 근거를 찾지 않는다.
+8. 이미 있는 규칙이면 `already-covered`로 보고하고 새 승격 후보로 만들지 않는다.
+9. 새 후보가 있으면 `core`, `project-local`, `global` 중 하나 이상으로 분류하고, 추천 위치를 제안한다.
+10. 최종 승격 후보가 없더라도 `near-miss / discarded candidates`를 먼저 짧게 보고한 뒤 `no-promotion` 결정을 제안한다.
+11. 사용자 승인 전에는 파일을 수정하지 않는다.
+12. 승인된 범위만 수정한다.
+13. 마지막에 반드시 `ai-ops context-promotion resolve ...`를 실행한다.
+14. 다시 `ai-ops context-promotion status`를 실행해 현재 `HEAD` receipt 확인을 한다.
+15. 승격 파일을 수정했더라도 직접 commit하지 않고 사용자 검사 대기 상태로 멈춘다.
 
 ## 보고 형식
 
 사용자에게 먼저 다음 형식으로 짧게 보고한다.
 
 - `new candidates`: 새로 승격할 후보와 추천 scope/위치
-- `already-covered`: 기존 context layer에 이미 있는 규칙과 근거 파일
+- `already-covered`: 기존 Active context layer에 이미 있는 같은 agent 행동 규칙과 근거 파일
+- `near-miss / discarded candidates`: 검토했지만 최종 승격 후보로 올리지 않은 항목과 이유
 - `no-promotion`: 승격하지 않을 항목과 이유
 - `ask`: 사용자가 선택해야 할 결정
 
 보고에는 각 후보의 근거를 함께 둔다. 근거는 현재 대화에서 반복된 판단, 사용자가 교정한 문장, 실행한 명령 루틴, 방금 완료된 `HEAD` 커밋 중 하나 이상이어야 한다.
+plan, test, README, runbook, operator docs는 후보 근거가 될 수 있지만, Active context layer에 같은 agent 행동 규칙이 없으면 자동으로 `already-covered`가 되지 않는다.
 
 ## Resolve 규칙
 
@@ -83,6 +93,6 @@ ai-ops context-promotion resolve --decision no-promotion --summary "이번 작
 - 웹 검색 금지: 이 검토는 외부 문서나 웹 검색을 사용하지 않는다.
 - 다른 repo 탐색 금지: parent directory, sibling repo, 이전 대화 workspace를 cross-check 근거로 사용하지 않는다.
 - receipt 확인 필수: 완료 전에 `ai-ops context-promotion status`에서 현재 `HEAD` receipt가 `found`인지 확인한다.
-- 기존 규칙 중복 금지: 이미 있는 규칙은 새 문서나 중복 문장으로 승격하지 않는다.
+- 기존 규칙 중복 금지: Active context layer에 이미 같은 agent 행동 규칙이 있으면 새 문서나 중복 문장으로 승격하지 않는다.
 - `Reserved` 승격 금지: 명시 승인 없이 `Reserved` 문서를 현재 판단 근거로 바꾸지 않는다.
 - 직접 commit 금지: 승격 수정 후에도 commit하지 않고 사용자 검사 대기 상태로 멈춘다.