ai-ops-cli 1.3.0 → 1.4.0

package/README.ko.md

@@ -44,11 +44,13 @@ GEMINI.md
 CLAUDE.md
 docs/agent/rules/00-agent-baseline.md
 docs/agent/workflow.md
+docs/agent/terminology.md
 docs/agent/rules/routing-rules.md
 docs/agent/rules/doc-update-rules.md
 docs/agent/rules/stop-rules.md
 docs/agent/checks/impact-checklist.md
 docs/agent/maps/codebase-map.md
+docs/business/terminology.md
 docs/business/business-rules.md
 docs/docs-status.md
 .ai-ops/manifest.json
@@ -76,7 +78,7 @@ receipts/config/*
 
 ### 사용자가 직접 수정해야 하는 파일은 무엇인가요?
 
-프로젝트 지식은 project-owned 문서에 적습니다. 기본 project-owned 문서는 `docs/agent/maps/codebase-map.md`, `docs/business/business-rules.md`, `docs/docs-status.md`입니다. `docs/agent/maps/codebase-map.md`와 `docs/business/business-rules.md`는 처음에는 Reserved 템플릿이지만, 프로젝트가 실제 내용을 채운 뒤에는 update가 자동으로 덮어쓰지 않습니다.
+프로젝트 지식은 project-owned 문서에 적습니다. 기본 project-owned 문서는 `docs/agent/maps/codebase-map.md`, `docs/business/terminology.md`, `docs/business/business-rules.md`, `docs/docs-status.md`입니다. `docs/agent/maps/codebase-map.md`, `docs/business/terminology.md`, `docs/business/business-rules.md`는 처음에는 Reserved 템플릿이지만, 프로젝트가 실제 내용을 채운 뒤에는 update가 자동으로 덮어쓰지 않습니다.
 
 `docs/docs-status.md`는 project-owned 문서이지만 자유 메모장이 아니라 context-layer registry입니다. 문서 status/frontmatter를 바꿀 때 함께 맞추는 파일이며, update 과정에서 manifest와 실제 문서 frontmatter 기준으로 테이블이 정리될 수 있습니다.
 
@@ -100,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
@@ -107,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
@@ -176,7 +187,7 @@ ai-ops pack update spec-lifecycle
 ai-ops pack uninstall spec-lifecycle
 ```
 
-`spec-lifecycle` pack은 `docs/specs/README.md`, `docs/specs/README.ko.md`, `docs/specs/baseline/.gitkeep`, `docs/specs/initial-build/.gitkeep`를 설치합니다. Markdown 문서만 context-layer와 `docs/docs-status.md` 감사 대상이고, `.gitkeep`은 manifest의 일반 pack file로만 기록됩니다.
+`spec-lifecycle` pack은 `docs/specs/README.md`, `docs/specs/README.ko.md`, `docs/specs/baseline/.gitkeep`, `docs/specs/initial-build/.gitkeep`를 설치합니다. Markdown 문서만 context-layer와 `docs/docs-status.md` 감사 대상이고, `.gitkeep`은 manifest의 일반 pack file로만 기록됩니다. 프로젝트 용어는 계속 `docs/business/terminology.md`에서 중앙 관리합니다.
 
 ## Deprecated Old Model
 

package/README.md

@@ -44,11 +44,13 @@ GEMINI.md
 CLAUDE.md
 docs/agent/rules/00-agent-baseline.md
 docs/agent/workflow.md
+docs/agent/terminology.md
 docs/agent/rules/routing-rules.md
 docs/agent/rules/doc-update-rules.md
 docs/agent/rules/stop-rules.md
 docs/agent/checks/impact-checklist.md
 docs/agent/maps/codebase-map.md
+docs/business/terminology.md
 docs/business/business-rules.md
 docs/docs-status.md
 .ai-ops/manifest.json
@@ -76,7 +78,7 @@ receipts/config/*
 
 ### Which files should users edit directly?
 
-Project knowledge belongs in project-owned documents. The default project-owned documents are `docs/agent/maps/codebase-map.md`, `docs/business/business-rules.md`, and `docs/docs-status.md`. `docs/agent/maps/codebase-map.md` and `docs/business/business-rules.md` start as Reserved templates, but once the project fills them with real content, update does not automatically overwrite them.
+Project knowledge belongs in project-owned documents. The default project-owned documents are `docs/agent/maps/codebase-map.md`, `docs/business/terminology.md`, `docs/business/business-rules.md`, and `docs/docs-status.md`. `docs/agent/maps/codebase-map.md`, `docs/business/terminology.md`, and `docs/business/business-rules.md` start as Reserved templates, but once the project fills them with real content, update does not automatically overwrite them.
 
 `docs/docs-status.md` is project-owned, but it is not a free-form notebook. It is the context-layer registry. Update it together with document status/frontmatter changes; the update flow may also normalize its table from the manifest and current document frontmatter.
 
@@ -100,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
@@ -107,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
@@ -176,7 +187,7 @@ ai-ops pack update spec-lifecycle
 ai-ops pack uninstall spec-lifecycle
 ```
 
-The `spec-lifecycle` pack installs `docs/specs/README.md`, `docs/specs/README.ko.md`, `docs/specs/baseline/.gitkeep`, and `docs/specs/initial-build/.gitkeep`. Only Markdown documents are audited by the context-layer and `docs/docs-status.md`; `.gitkeep` files are tracked only as regular pack files in the manifest.
+The `spec-lifecycle` pack installs `docs/specs/README.md`, `docs/specs/README.ko.md`, `docs/specs/baseline/.gitkeep`, and `docs/specs/initial-build/.gitkeep`. Only Markdown documents are audited by the context-layer and `docs/docs-status.md`; `.gitkeep` files are tracked only as regular pack files in the manifest. Project terminology remains centralized in `docs/business/terminology.md`.
 
 ## Deprecated Old Model
 

package/data/context-layer/AGENTS.md

@@ -16,9 +16,10 @@ update_when:
 1. `AGENTS.md`
 2. `docs/agent/rules/00-agent-baseline.md`
 3. `docs/agent/workflow.md`
-4. 나머지 `docs/agent/rules/*.md`
-5. 변경 영향 확인이 필요하면 `docs/agent/checks/impact-checklist.md`
-6. `docs/docs-status.md`
+4. `docs/agent/terminology.md`
+5. 나머지 `docs/agent/rules/*.md`
+6. 변경 영향 확인이 필요하면 `docs/agent/checks/impact-checklist.md`
+7. `docs/docs-status.md`
 
 ## 문서 신뢰도
 

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/context-layer/docs/agent/terminology.md

@@ -0,0 +1,39 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+  - terminology_check
+update_when:
+  - operating_layer_changes
+  - terminology_changes
+---
+# Agent Terminology
+
+이 문서는 project operating layer를 해석하는 데 필요한 최소 용어만 정의한다. `ai-ops-cli`의 release, 내부 구현, phase history, integration catalog 구현 세부사항은 사용자 프로젝트의 기본 운영 문서에 포함하지 않는다.
+
+## 핵심 용어
+
+| 용어 | 정의 |
+| --- | --- |
+| agent operating layer | 프로젝트 안에서 에이전트가 읽고 따르는 운영 문서와 상태 파일의 묶음이다. |
+| context layer | operating layer 문서의 경로, 상태, 읽기 조건, 갱신 조건, content hash를 추적하는 문맥 index다. |
+| `docs/docs-status.md` | operating layer 문서의 status와 owner를 사람이 확인할 수 있게 기록하는 project-owned registry다. |
+| `.ai-ops/context-layer.json` | 에이전트와 CLI가 문서 계층을 빠르게 탐색하고 audit할 수 있게 생성하는 index 파일이다. |
+| `Active` | 현재 판단 근거로 사용할 수 있는 문서 상태다. |
+| `Reserved` | 자리만 만든 문서 상태다. 프로젝트가 실제 내용을 보강하기 전까지 판단 근거로 사용하지 않는다. |
+| `Draft` | 작성 중인 문서 상태다. 현재 판단 근거로 쓰기 전에 검토가 필요하다. |
+| `Archived` | 과거 기록 상태다. 현재 운영 판단에 사용하지 않는다. |
+| ai-ops managed | CLI 템플릿이 관리하는 문서 또는 문서 영역이다. update 시 현재 CLI 템플릿으로 다시 적용될 수 있다. |
+| project-owned | 프로젝트가 직접 채우고 유지하는 문서다. CLI update는 사용자 내용을 보존해야 한다. |
+| optional pack | 필요한 프로젝트에만 설치하는 추가 문서 묶음이다. 기본 operating layer와 별도의 lifecycle을 가진다. |
+| `read_when` | 에이전트가 이 문서를 읽어야 하는 상황을 나타내는 frontmatter 필드다. |
+| `update_when` | 문서를 갱신해야 하는 변경 상황을 나타내는 frontmatter 필드다. |
+
+## 범위 밖
+
+- `ai-ops-cli` release model
+- `ai-ops-cli` 내부 phase history
+- CLI 구현 파일이나 schema의 내부 구조
+- integration catalog의 구현 세부사항

package/data/context-layer/docs/business/terminology.md

@@ -0,0 +1,61 @@
+---
+status: Reserved
+layer: business
+owner: project
+read_when:
+  - terminology_check
+  - business_rule_check
+  - spec_lifecycle
+update_when:
+  - terminology_changes
+  - business_rule_changes
+  - spec_lifecycle_changes
+---
+# Terminology
+
+이 문서는 Reserved 상태입니다. 프로젝트가 실제 용어를 보강하기 전까지 현재 판단 근거로 사용하지 마세요.
+
+프로젝트의 비즈니스, spec, UI, work packet, plan 용어는 이 문서를 source of truth로 사용합니다. `docs/specs/`가 설치되어 있어도 별도 용어 문서를 두지 않고 이 문서를 읽고 갱신합니다.
+
+## 용어 표기 원칙
+
+- 사용자-facing 또는 domain 용어는 한국어를 우선합니다.
+- code-facing name, API field, library/service name, protocol, file path, 표준 technical term은 영어 원형이 더 명확하면 그대로 씁니다.
+- 같은 개념은 하나의 canonical term으로 통일합니다.
+- 불확실한 용어는 확정하지 말고 `검토 중인 용어`에 기록합니다.
+
+## 핵심 용어
+
+| 용어 | 영문 / 코드명 | 정의 | 사용 범위 | 허용 별칭 | 금지 표현 | 관련 문서 |
+| --- | --- | --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+
+## 엔티티 용어
+
+| 용어 | 영문 / 코드명 | 정의 | 사용 범위 | 허용 별칭 | 금지 표현 | 관련 문서 |
+| --- | --- | --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+
+## 상태 용어
+
+| 용어 | 영문 / 코드명 | 정의 | 사용 범위 | 허용 별칭 | 금지 표현 | 관련 문서 |
+| --- | --- | --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+
+## UI 용어
+
+| 용어 | 영문 / 코드명 | 정의 | 사용 범위 | 허용 별칭 | 금지 표현 | 관련 문서 |
+| --- | --- | --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+
+## 금지하거나 피할 표현
+
+| 표현 | 이유 | 대신 사용할 표현 |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## 검토 중인 용어
+
+| 항목 | 후보 표현 | 충돌 / 불확실성 | 판단 메모 | 관련 문서 |
+| --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | TBD |

package/data/packs/spec-lifecycle/docs/specs/README.ko.md

@@ -25,4 +25,5 @@ docs/specs/
 
 - `baseline/`은 승인된 제품/기술/UI 기준 문서를 둡니다.
 - `initial-build/`는 초기 구현 work packet과 관련 산출물을 둡니다.
+- 프로젝트 용어는 `docs/business/terminology.md`를 기준으로 관리합니다. 이 optional spec pack은 별도 용어 source of truth를 만들지 않습니다.
 - 실제 판단 근거로 쓰기 전에 각 문서의 frontmatter와 `docs/docs-status.md` 상태를 갱신합니다.

package/data/packs/spec-lifecycle/docs/specs/README.md

@@ -25,4 +25,5 @@ docs/specs/
 
 - `baseline/` contains approved product, technical, and UI baseline documents.
 - `initial-build/` contains initial implementation work packets and related artifacts.
+- Project terminology is tracked in `docs/business/terminology.md`; this optional spec pack does not create a separate terminology source of truth.
 - Before using any document as decision-making evidence, update its frontmatter and its status in `docs/docs-status.md`.

package/data/skills/skill-registry.json

@@ -169,11 +169,11 @@
       "source_path": "task-skills/spec-product-05-spec-to-work-packets"
     },
     {
-      "id": "spec-shared-glossary-sync",
+      "id": "project-terminology-sync",
       "kind": "task",
       "supported_tools": ["claude-code", "codex", "gemini"],
       "groups": ["spec-lifecycle"],
-      "source_path": "task-skills/spec-shared-glossary-sync"
+      "source_path": "task-skills/project-terminology-sync"
     },
     {
       "id": "typescript-language",

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하지 않고 사용자 검사 대기 상태로 멈춘다.

package/data/skills/task-skills/{spec-shared-glossary-sync → project-terminology-sync}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: spec-shared-glossary-sync
-description: Create or update a Korean 01_glossary.md inside the current project's docs/specs/baseline directory by standardizing domain terms, entities, states, UI labels, and English code-facing names across baseline docs and active .codex/plans.
+name: project-terminology-sync
+description: Create or update the current project's docs/business/terminology.md by standardizing project-wide domain terms, entities, states, UI labels, and English code-facing names across business docs, specs, active .codex/plans, and work packets.
 disable-model-invocation: true
 ---
 
-# spec-shared-glossary-sync
+# project-terminology-sync
 
-Use this skill when the project needs a shared glossary or when existing docs/specs/plans have begun to drift in terminology.
+Use this skill when the project needs canonical terminology or when existing business docs, specs, plans, or packets have begun to drift in terminology.
 
 Typical high-value run points are:
 
@@ -14,6 +14,7 @@ Typical high-value run points are:
 - after `product spec`
 - after `ui spec`
 - during `spec-baseline-sync` if implemented terminology changed
+- after business rule changes introduce new domain language
 - whenever naming drift is noticed
 
 Usually skip automatic reruns after small plans unless new shared terminology was introduced.
@@ -21,18 +22,18 @@ Usually skip automatic reruns after small plans unless new shared terminology wa
 ## Output Location
 
 - Write into the current workspace.
-- Default output path: `./docs/specs/baseline/01_glossary.md`
+- Default output path: `./docs/business/terminology.md`
 
 ## Language Rules
 
-- Write the glossary in Korean.
+- Write terminology content in Korean.
 - Keep code-facing English identifiers, API field names, library/service names, protocol names, file paths, and standard technical terms in their natural English form when clearer.
 - Do not invent awkward Koreanized spellings for standard English technical terms.
 - If a term needs explanation, keep the standard term and add a short Korean definition.
 
 ## Objective
 
-Maintain one canonical vocabulary so briefs, specs, UI docs, plans, packets, and baseline sync entries use the same terms for the same concepts.
+Maintain one canonical project vocabulary so business docs, briefs, specs, UI docs, plans, packets, and baseline sync entries use the same terms for the same concepts.
 
 The default output style is:
 
@@ -42,10 +43,14 @@ The default output style is:
 
 ## Create Or Update Rules
 
-- If `./docs/specs/baseline/01_glossary.md` does not exist, create it from currently approved specs and relevant active plans.
+- If `./docs/business/terminology.md` does not exist, create it with operating-layer frontmatter from `references/template.md`.
 - If it exists, update it instead of replacing it blindly.
+- Preserve existing frontmatter unless the document is being promoted from `Reserved` to `Active`.
+- When the document receives real terminology content, set frontmatter `status: Active`.
+- If `docs/docs-status.md` exists, update the `docs/business/terminology.md` row to match the frontmatter status and owner.
+- If `.ai-ops/context-layer.json` exists, update the `docs/business/terminology.md` entry so status, read/update conditions, and content hash match the file.
 - Preserve stable canonical terms unless there is a strong reason to change them.
-- If a newly found term conflicts with an existing definition, keep the current canonical term and record the conflict in `정의 충돌 / 검토 필요`.
+- If a newly found term conflicts with an existing definition, keep the current canonical term and record the conflict in `검토 중인 용어`.
 - Normalize synonyms toward one preferred term.
 - Prefer Korean for user-facing/domain wording, but keep standard English when clearer, more stable, or already established in the project.
 
@@ -53,13 +58,14 @@ The default output style is:
 
 Read relevant files that exist:
 
+- `./docs/business/terminology.md`
+- `./docs/business/business-rules.md`
 - `./docs/specs/baseline/00_brief.md`
 - `./docs/specs/baseline/05_technical-context.md`
 - `./docs/specs/baseline/10_product-spec.md`
 - `./docs/specs/baseline/20_ui-spec.md`
 - active `./.codex/plans/*.md` when terminology from a current change needs to become canonical
 - `./docs/specs/initial-build/<topic>/30_work-packets/*.md` when reviewing initial build terminology
-- existing `./docs/specs/baseline/01_glossary.md`
 
 Use only files that are present and relevant.
 
@@ -71,9 +77,11 @@ Use only files that are present and relevant.
 4. Attach English code-facing counterpart when needed.
 5. Capture harmless synonyms only when useful.
 6. List discouraged or banned wording when ambiguity is likely.
-7. Write most glossary content as tables.
-8. Move only hard cases into detailed sections.
-9. Update the glossary without deleting still-valid prior decisions.
+7. Promote `docs/business/terminology.md` from `Reserved` to `Active` if real terminology is written.
+8. Write most terminology content as tables.
+9. Move only hard cases into detailed sections.
+10. Update `docs/docs-status.md` and `.ai-ops/context-layer.json` when they exist.
+11. Update terminology without deleting still-valid prior decisions.
 
 Use these references while drafting:
 
@@ -87,13 +95,14 @@ Use these references while drafting:
 - `상태 용어`
 - `UI 용어`
 - `금지하거나 피할 표현`
-- `복잡한 개념 상세 설명`
-- `정의 충돌 / 검토 필요`
+- `검토 중인 용어`
 
 ## Quality Bar
 
-The glossary is not ready if:
+The terminology document is not ready if:
 
+- frontmatter is missing or the document has real terminology but still says `status: Reserved`
+- `docs/docs-status.md` or `.ai-ops/context-layer.json` disagree with the terminology document status when those files exist
 - simple vocabulary that should be in tables is expanded into unnecessary prose
 - the same concept still appears under multiple primary names
 - terms are listed without definitions

package/data/skills/task-skills/project-terminology-sync/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "project-terminology-sync"
+  short_description: "Standardize project terms into docs/business/terminology.md."
+  default_prompt: "Use $project-terminology-sync to create or update docs/business/terminology.md, standardizing project-wide terms across business docs, specs, active .codex/plans, and work packets."
+policy:
+  allow_implicit_invocation: false

package/data/skills/task-skills/{spec-shared-glossary-sync → project-terminology-sync}/references/checklist.md

@@ -1,6 +1,6 @@
-# Glossary Sync Checklist
+# Project Terminology Sync Checklist
 
-Use this checklist before finalizing `01_glossary.md`.
+Use this checklist before finalizing `docs/business/terminology.md`.
 
 ## Look For
 
@@ -30,7 +30,7 @@ Use this checklist before finalizing `01_glossary.md`.
 
 ## Update Rule
 
-- merge new terms into the existing glossary
+- merge new terms into the existing terminology document
 - do not delete stable terms unless they are clearly wrong
-- when uncertain, add the conflict to `정의 충돌 / 검토 필요`
-- keep simple terms in tables; avoid turning the whole glossary into long prose
+- when uncertain, add the conflict to `검토 중인 용어`
+- keep simple terms in tables; avoid turning the whole terminology document into long prose

package/data/skills/task-skills/{spec-shared-glossary-sync → project-terminology-sync}/references/template.md

@@ -1,7 +1,20 @@
-# 01_glossary.md Template
+# docs/business/terminology.md Template
 
 ```md
-# 01 Glossary
+---
+status: Active
+layer: business
+owner: project
+read_when:
+  - terminology_check
+  - business_rule_check
+  - spec_lifecycle
+update_when:
+  - terminology_changes
+  - business_rule_changes
+  - spec_lifecycle_changes
+---
+# Terminology
 
 용어 표기 원칙:
 
@@ -38,21 +51,9 @@
 |---|---|---|
 | 표현 1 | 왜 피해야 하는지 | 표준 표현 |
 
-## 복잡한 개념 상세 설명
+## 검토 중인 용어
 
-### 개념 1
-
-- 왜 이 개념이 표만으로는 충분하지 않은지 설명
-- 어떤 문맥에서 다른 표현과 충돌하는지 설명
-
-```mermaid
-flowchart TD
-    A["개념 A"] --> B["개념 B"]
-```
-
-## 정의 충돌 / 검토 필요
-
-| 항목 | 현재 표준 | 충돌 표현 | 판단 메모 |
-|---|---|---|---|
-| 충돌 항목 | 현재 표준 표현 | 새로 발견된 표현 | 판단 메모 |
+| 항목 | 후보 표현 | 충돌 / 불확실성 | 판단 메모 | 관련 문서 |
+|---|---|---|---|---|
+| 충돌 항목 | 새로 발견된 표현 | 현재 표준 표현과의 차이 | 판단 메모 | `10_product-spec.md` |
 ```

package/data/skills/task-skills/spec-baseline-sync/SKILL.md

@@ -10,7 +10,7 @@ Use this skill after a post-MVP change has been implemented and verified, and th
 
 ## Output Location
 
-- Update only affected files under `./docs/specs/baseline/`.
+- Update only affected files under `./docs/specs/baseline/` and `./docs/business/terminology.md` when project terminology changed.
 - Move the completed plan from `./.codex/plans/<plan>.md` to `./.codex/plans/archived/YYYY-MM/<plan>.md`.
 - Append a compact entry to `./.codex/CHANGE_LOG.md`.
 
@@ -31,7 +31,7 @@ Read the relevant available inputs before updating baseline:
 2. implemented code changes, PR diff, commit diff, or implementation notes
 3. verification results and known skipped tests
 4. optional issue or PR link
-5. existing `./docs/specs/baseline/01_glossary.md`
+5. existing `./docs/business/terminology.md`
 6. existing `./docs/specs/baseline/05_technical-context.md`
 7. existing `./docs/specs/baseline/10_product-spec.md`
 8. existing `./docs/specs/baseline/20_ui-spec.md`
@@ -64,7 +64,7 @@ Baseline sync is implementation-confirming work.
 
 1. Identify the plan being closed and the implementation evidence.
 2. Compare shipped behavior against current baseline docs.
-3. Decide which baseline docs are affected among `01,05,10,20,22,24`.
+3. Decide whether project terminology or baseline docs among `05,10,20,22,24` are affected.
 4. Update only affected baseline docs while preserving still-valid prior decisions.
 5. Append one changelog entry summarizing what changed, why, evidence, baseline impact, and follow-up.
 6. Move the plan into `.codex/plans/archived/YYYY-MM/`.
@@ -74,7 +74,7 @@ Use [references/template.md](references/template.md) for the changelog entry sha
 
 ## Baseline Update Rules
 
-- `./docs/specs/baseline/01_glossary.md`: update only when the implementation introduced or normalized meaningful shared terms.
+- `./docs/business/terminology.md`: update only when the implementation introduced or normalized meaningful shared terms.
 - `./docs/specs/baseline/05_technical-context.md`: update only when architecture, stack, boundaries, integrations, or deployment assumptions changed materially.
 - `./docs/specs/baseline/10_product-spec.md`: update for implemented user-flow, feature, entity, rule, edge-case, or success-criteria changes.
 - `./docs/specs/baseline/20_ui-spec.md`: update for implemented screens, states, interactions, or UI constraints.

package/data/skills/task-skills/spec-product-01-idea-to-brief/SKILL.md

@@ -20,10 +20,10 @@ Use this skill when the input is still rough and the next artifact should be `./
 - Do not force awkward phonetic transliterations such as `소스 오브 트루스`, `타겟 플랫폼`, or `워크 패킷`.
 - If an English technical term needs explanation, keep the English term and add a short Korean gloss on first mention, for example `source of truth(가장 신뢰하는 기준)`.
 
-## Glossary Rule
+## Terminology Rule
 
-- Check `./docs/specs/baseline/01_glossary.md` only if it exists and the brief introduces product terms, user-facing labels, or domain nouns that may collide with existing terminology.
-- After writing the target document, `spec-shared-glossary-sync` is recommended because briefs often introduce new canonical terms.
+- Check `./docs/business/terminology.md` if it exists and the brief introduces product terms, user-facing labels, or domain nouns that may collide with existing terminology.
+- After writing the target document, `project-terminology-sync` is recommended because briefs often introduce new canonical terms.
 
 ## Objective
 

package/data/skills/task-skills/spec-product-02-brief-to-technical-context/SKILL.md

@@ -20,10 +20,10 @@ Use this skill after `./docs/specs/baseline/00_brief.md` is approved and before
 - Do not force awkward phonetic transliterations such as `소스 오브 트루스`, `타겟 플랫폼`, or `워크 패킷`.
 - If an English technical term needs explanation, keep the English term and add a short Korean gloss on first mention, for example `source of truth(가장 신뢰하는 기준)`.
 
-## Glossary Rule
+## Terminology Rule
 
-- Check `./docs/specs/baseline/01_glossary.md` only if it exists and the document introduces stack names, architectural terms, or labels that should align with existing terminology.
-- After writing the target document, run `spec-shared-glossary-sync` only if new technical terms, product-facing labels, or collisions were introduced.
+- Check `./docs/business/terminology.md` if it exists and the document introduces stack names, architectural terms, or labels that should align with existing terminology.
+- After writing the target document, run `project-terminology-sync` only if new technical terms, product-facing labels, or collisions were introduced.
 
 ## Default Stack Preferences