ai-ops-cli 1.3.1 → 1.4.0

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

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

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 문서가 더 구체적인 판단 근거를 제공하면 그 문서를 우선한다.
@@ -44,4 +45,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하지 않고 사용자 검사 대기 상태로 멈춘다.