ai-ops-cli 0.2.6 → 1.0.1

package/README.ko.md

@@ -0,0 +1,170 @@
+# ai-ops-cli
+
+`ai-ops-cli`는 프로젝트에 AI agent operating layer를 설치하고, 사용자 환경에 agent skills/subagents를 설치하는 CLI입니다.
+
+이 문서는 현재 구현된 breaking model을 설명합니다. old rules + skills scaffolder 모델은 deprecated 문맥으로만 남깁니다.
+
+## Current Breaking Model
+
+```mermaid
+flowchart TD
+  init["ai-ops init"] --> layer["Project operating layer 설치"]
+  layer --> entry["AGENTS.md canonical entrypoint"]
+  layer --> adapters["GEMINI.md / CLAUDE.md adapters"]
+  layer --> docs["docs/agent/* / docs/business/*"]
+  layer --> state[".ai-ops/manifest.json / context-layer.json"]
+
+  skill["ai-ops skill ..."] --> globalSkills["Global skills only"]
+  subagent["ai-ops subagent ..."] --> globalSubagents["Global subagents only"]
+  pack["ai-ops pack ..."] --> docsSpecs["optional docs/specs/ pack"]
+```
+
+핵심 경계:
+
+- project scope는 operating layer 문서만 관리합니다.
+- global scope는 skills/subagents만 관리합니다.
+- `AGENTS.md`가 canonical entrypoint입니다.
+- `GEMINI.md`와 `CLAUDE.md`는 `AGENTS.md`를 기준으로 삼게 하는 adapter입니다.
+- `docs/specs/`는 optional pack 위치입니다.
+- global asset 명령은 `AI_OPS_HOME` 또는 `HOME`이 없으면 cwd fallback 없이 실패합니다.
+
+## 설치 대상
+
+Project repo:
+
+```text
+AGENTS.md
+GEMINI.md
+CLAUDE.md
+docs/agent/workflow.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/checks/review-checklist.md
+docs/agent/maps/codebase-map.md
+docs/business/business-rules.md
+docs/docs-status.md
+.ai-ops/manifest.json
+.ai-ops/context-layer.json
+```
+
+Global tool home:
+
+```text
+skills/*
+subagents/*
+```
+
+## 목표 CLI 표면
+
+```text
+ai-ops [command]
+
+Commands:
+  init       Install or refresh the project agent operating layer
+  diff       Show drift in the project operating layer
+  update     Re-apply the project operating layer
+  audit      Check frontmatter, docs-status, manifest, and context-layer consistency
+  uninstall  Remove project-managed operating layer files
+  skill      Manage global agent skills
+  subagent   Manage global agent subagents
+  pack       Manage optional project operating layer packs
+```
+
+`--tool`은 유지합니다. Codex, Claude Code, Gemini CLI가 서로 다른 discovery 위치와 adapter 파일을 사용하기 때문입니다.
+
+Skill lifecycle 명령:
+
+```bash
+ai-ops skill list
+ai-ops skill install skill-load-check --tool codex
+ai-ops skill install doc-impact-reviewer --tool codex
+ai-ops skill diff
+ai-ops skill update
+ai-ops skill uninstall skill-load-check
+```
+
+`doc-impact-reviewer`는 변경 완료 또는 커밋 직전에 운영 문서 영향도를 확인하는 수동 task skill입니다. `$doc-impact-reviewer`로 호출하면 git status/diff를 보고 `required / recommended / not needed` 문서 후보와 미갱신 리스크를 제안합니다. 사용자 승인 전에는 문서를 수정하지 않고, 직접 staging/commit도 하지 않습니다.
+
+Subagent lifecycle 명령:
+
+```bash
+ai-ops subagent list
+ai-ops subagent install security-gate --tool codex
+ai-ops subagent diff
+ai-ops subagent update
+ai-ops subagent uninstall security-gate
+```
+
+Subagent는 항상 global tool home에 설치됩니다. Codex는 `.codex/agents/<id>.toml`, Claude Code는 `.claude/agents/<id>.md`, Gemini CLI는 `.gemini/agents/<id>.md`를 사용하고, 상태는 `.ai-ops/subagents-manifest.json`에만 기록합니다.
+
+Pack lifecycle 명령:
+
+```bash
+ai-ops init --tool codex
+ai-ops pack list
+ai-ops pack install spec-lifecycle
+ai-ops pack diff spec-lifecycle
+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로만 기록됩니다.
+
+## Deprecated Old Model
+
+다음 동작은 현재 코드나 과거 README에 남아 있을 수 있지만 새 계약에서는 제거 대상입니다.
+
+- preset-first init UX
+- project scope skill 설치
+- `ai-ops skill install --project`
+- project-installed skill metadata
+- `.ai-ops-manifest.json`
+- legacy manifest migration
+- root `specs/`
+- `ai-ops spec init`
+
+기존 프로젝트 자동 마이그레이션은 제공하지 않습니다. 기존 사용자는 old CLI로 `ai-ops uninstall`을 실행한 뒤 새 major CLI로 `ai-ops init`을 다시 실행합니다.
+
+## Old Model Command Notes
+
+Deprecated old model 문맥에서만 아래 명령을 과거 project scope skill 설치 예시로 남깁니다. 현재 skill CLI는 global-only이며 `--project`, `--global`, `--scope`를 공개 옵션으로 제공하지 않습니다.
+
+```bash
+ai-ops skill install skill-load-check --project --tool codex
+```
+
+Deprecated old model 문맥에서만 유지되는 항목:
+
+- `--project`는 project scope skill 설치용 old option입니다.
+- `--global`, `--scope`는 skill scope를 직접 지정하던 old option입니다.
+- `spec init`은 root `specs/`를 만들던 제거된 old command입니다.
+- `.ai-ops-manifest.json`는 old project manifest입니다.
+
+## 개발
+
+저장소 루트 기준:
+
+```bash
+npm install
+npm run build
+npm run compile
+npm test
+```
+
+CLI workspace만 확인할 때:
+
+```bash
+npm run build --workspace=apps/cli
+npm run test --workspace=apps/cli
+```
+
+코드와 운영 문서 변경은 `npm run check`를 기본 검증으로 사용합니다. CLI 배포 산출물 확인은 `npm run build`와 `npm run compile`을 함께 사용합니다.
+
+Self-dogfood 검증은 `npm run build` 후 이 repo에 `init --tool codex --tool gemini --tool claude-code`를 적용하고, `diff`, `audit`, `update --force`, `uninstall --yes`, 재-`init`, 재-`audit` 순서로 확인합니다. 이 repo에는 `spec-lifecycle` pack을 설치하지 않고 `pack list`에서 `not installed` 상태만 확인합니다.
+
+## 관련 문서
+
+- [Master blueprint](../../docs/plan.md)
+- [Implementation playbook](../../docs/implementation-playbook.md)

package/README.md

@@ -1,165 +1,150 @@
 # ai-ops-cli
 
-CLI for managing core AI tool rules and agent skills across projects.
+`ai-ops-cli`는 프로젝트에 AI agent operating layer를 설치하고, 사용자 환경에 agent skills/subagents를 설치하는 CLI입니다.
 
-## Why this exists
+이 문서는 현재 구현된 breaking model을 설명합니다. old rules + skills scaffolder 모델은 deprecated 문맥으로만 남깁니다.
 
-`ai-ops-cli` reduces configuration drift across AI coding tools.
+## Current Breaking Model
 
-- different tools use different file layouts and loading models
-- manual sync across tools is error-prone over time
-- teams need a deterministic setup for shared core rules and installable skills
+```mermaid
+flowchart TD
+  init["ai-ops init"] --> layer["Project operating layer 설치"]
+  layer --> entry["AGENTS.md canonical entrypoint"]
+  layer --> adapters["GEMINI.md / CLAUDE.md adapters"]
+  layer --> docs["docs/agent/* / docs/business/*"]
+  layer --> state[".ai-ops/manifest.json / context-layer.json"]
 
-The CLI treats these as separate sources of truth:
-
-- `apps/cli/data/rules/*.yaml`: always-loaded core rules only
-- `apps/cli/data/skills/skill-registry.json`: install/catalog metadata for skills
-- `apps/cli/data/skills/reference-skills/<skill-id>/`: installable reference skills
-- `apps/cli/data/skills/task-skills/<skill-id>/`: installable task skills
-- `apps/cli/data/presets.yaml`: preset-to-core-rule mapping
-
-## What this CLI provides
+  skill["ai-ops skill ..."] --> globalSkills["Global skills only"]
+  subagent["ai-ops subagent ..."] --> globalSubagents["Global subagents only"]
+  pack["ai-ops pack ..."] --> docsSpecs["optional docs/specs/ pack"]
+```
 
-- interactive project initialization (`ai-ops init`)
-- skill package installation and lifecycle management (`ai-ops skill ...`)
-- spec pipeline directory scaffolding (`ai-ops spec init`)
-- source drift checks (`ai-ops diff`)
-- deterministic re-apply (`ai-ops update`)
-- managed cleanup (`ai-ops uninstall`)
+핵심 경계:
 
-## Supported tools and output layout
+- project scope는 operating layer 문서만 관리합니다.
+- global scope는 skills/subagents만 관리합니다.
+- `AGENTS.md`가 canonical entrypoint입니다.
+- `GEMINI.md`와 `CLAUDE.md`는 `AGENTS.md`를 기준으로 삼게 하는 adapter입니다.
+- `docs/specs/`는 optional pack 위치입니다.
+- global asset 명령은 `AI_OPS_HOME` 또는 `HOME`이 없으면 cwd fallback 없이 실패합니다.
 
-| Tool                        | Project rules output                                  | Skill output                 |
-| --------------------------- | ----------------------------------------------------- | ---------------------------- |
-| Claude Code (`claude-code`) | `.claude/rules/<rule-id>.md`, `<workspace>/CLAUDE.md` | `.claude/skills/<skill-id>/` |
-| Codex (`codex`)             | `AGENTS.md`, `<workspace>/AGENTS.override.md`         | `.agents/skills/<skill-id>/` |
-| Gemini CLI (`gemini`)       | `GEMINI.md`, `<workspace>/GEMINI.md`                  | `.agents/skills/<skill-id>/` |
+## 설치 대상
 
-Optional settings files:
+Project repo:
 
-- Claude Code: `.claude/settings.local.json`
-- Gemini CLI: `.gemini/settings.json`
-- Formatting protection section: `.prettierignore`
+```text
+AGENTS.md
+GEMINI.md
+CLAUDE.md
+docs/agent/workflow.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/checks/review-checklist.md
+docs/agent/maps/codebase-map.md
+docs/business/business-rules.md
+docs/docs-status.md
+.ai-ops/manifest.json
+.ai-ops/context-layer.json
+```
 
-## Install
+Global tool home:
 
-```bash
-npm install -g ai-ops-cli
+```text
+skills/*
+subagents/*
 ```
 
-## Usage
+## 목표 CLI 표면
 
-```bash
-# Initialize the current project
-ai-ops init
+```text
+ai-ops [command]
 
-# Install a skill globally (user scope by default)
-ai-ops skill install skill-load-check --tool codex
+Commands:
+  init       Install or refresh the project agent operating layer
+  diff       Show drift in the project operating layer
+  update     Re-apply the project operating layer
+  audit      Check frontmatter, docs-status, manifest, and context-layer consistency
+  uninstall  Remove project-managed operating layer files
+  skill      Manage global agent skills
+  subagent   Manage global agent subagents
+  pack       Manage optional project operating layer packs
+```
 
-# Install a skill only for the current project
-ai-ops skill install skill-load-check --project --tool codex
+`--tool`은 유지합니다. Codex, Claude Code, Gemini CLI가 서로 다른 discovery 위치와 adapter 파일을 사용하기 때문입니다.
+
+Skill lifecycle 명령:
 
-# Inspect or update installed skills
+```bash
 ai-ops skill list
+ai-ops skill install skill-load-check --tool codex
+ai-ops skill install doc-impact-reviewer --tool codex
 ai-ops skill diff
 ai-ops skill update
 ai-ops skill uninstall skill-load-check
-
-# Check project drift
-ai-ops diff
-
-# Re-apply current project state
-ai-ops update
-ai-ops update --force
-
-# Remove project-managed files
-ai-ops uninstall
-
-# Initialize spec pipeline directory structure
-ai-ops spec init
-
-# Force re-create even if specs/ already exists
-ai-ops spec init --force
 ```
 
-## CLI Surface
+`doc-impact-reviewer`는 변경 완료 또는 커밋 직전에 운영 문서 영향도를 확인하는 수동 task skill입니다. `$doc-impact-reviewer`로 호출하면 git status/diff를 보고 `required / recommended / not needed` 문서 후보와 미갱신 리스크를 제안합니다. 사용자 승인 전에는 문서를 수정하지 않고, 직접 staging/commit도 하지 않습니다.
 
-```text
-ai-ops [command]
+Subagent lifecycle 명령:
 
-Commands:
-  init       Initialize AI tool rules for a project
-  skill      Manage agent skills
-  spec       Manage spec pipeline
-  update     Update installed rules
-  diff       Show diff between installed and current rules
-  uninstall  Remove installed rules and manifest
-
-Options:
-  --force        Force update even when no changes are detected (update only)
-  -V, --version  Output version number
-  -h, --help     Display help
+```bash
+ai-ops subagent list
+ai-ops subagent install security-gate --tool codex
+ai-ops subagent diff
+ai-ops subagent update
+ai-ops subagent uninstall security-gate
 ```
 
-### `ai-ops spec` subcommands
+Subagent는 항상 global tool home에 설치됩니다. Codex는 `.codex/agents/<id>.toml`, Claude Code는 `.claude/agents/<id>.md`, Gemini CLI는 `.gemini/agents/<id>.md`를 사용하고, 상태는 `.ai-ops/subagents-manifest.json`에만 기록합니다.
 
-```text
-ai-ops spec init [options]
-
-  Initialize the specs/ directory structure for AI-collaborative spec pipelines.
-  Creates:
-    specs/README.md          — usage guide
-    specs/baseline/          — baseline spec documents
-    specs/delta/             — delta (incremental change) spec documents
+Pack lifecycle 명령:
 
-Options:
-  --force   Overwrite existing specs/ directory
+```bash
+ai-ops init --tool codex
+ai-ops pack list
+ai-ops pack install spec-lifecycle
+ai-ops pack diff spec-lifecycle
+ai-ops pack update spec-lifecycle
+ai-ops pack uninstall spec-lifecycle
 ```
 
-Notes:
+`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로만 기록됩니다.
 
-- Project installation state is tracked in `.ai-ops-manifest.json`.
-- User-scope skill state is tracked in `~/.ai-ops/skills-manifest.json`.
-- `ai-ops skill` defaults to user scope. Use `--project` to keep a skill local to the current repo.
+## Deprecated Old Model
 
-## Install / Update / Uninstall Behavior
+다음 동작은 현재 코드나 과거 README에 남아 있을 수 있지만 새 계약에서는 제거 대상입니다.
 
-- Managed project rule files are wrapped in an `ai-ops` section with metadata (`sourceHash`, `generatedAt`).
-- If a rule file already has an `ai-ops` section, only that section is replaced.
-- If a rule file has no managed section, generated content is appended and user content is preserved.
-- Skill packages are written into dedicated directories and replaced as full package trees on update.
-- `uninstall` removes only project-managed rule files and project-installed skill directories.
-- User-scope skills are never removed by `ai-ops uninstall`.
+- preset-first init UX
+- project scope skill 설치
+- `ai-ops skill install --project`
+- project-installed skill metadata
+- `.ai-ops-manifest.json`
+- legacy manifest migration
+- root `specs/`
+- `ai-ops spec init`
 
-## Init Flow Summary
+기존 프로젝트 자동 마이그레이션은 제공하지 않습니다. 기존 사용자는 old CLI로 `ai-ops uninstall`을 실행한 뒤 새 major CLI로 `ai-ops init`을 다시 실행합니다.
 
-`ai-ops init` prompts for:
+## Old Model Command Notes
 
-1. Tool selection (`claude-code`, `codex`, `gemini`)
-2. Monorepo confirmation
-3. Workspace selection for monorepos
-4. Preset selection per workspace
-5. Locked core rules review
-6. Preset-linked `reference` skills only:
-   - already-installed global skills are shown separately
-   - only installable skills can be deselected
-7. One shared install scope for selected installable skills (`user` default or `project`)
-8. Optional settings installation
+Deprecated old model 문맥에서만 아래 명령을 과거 project scope skill 설치 예시로 남깁니다. 현재 skill CLI는 global-only이며 `--project`, `--global`, `--scope`를 공개 옵션으로 제공하지 않습니다.
 
-Important behavior:
+```bash
+ai-ops skill install skill-load-check --project --tool codex
+```
 
-- core rules come from the preset directly and are not fine-tuned in `init`
-- `init` shows only preset-linked `reference` skills
-- `task` skills are excluded from `init` and are managed with `ai-ops skill install/uninstall`
-- globally available skills are not reinstalled by default
-- when `user` scope is chosen, selected skills are written only to the global skill registry
-- when `project` scope is chosen, selected skills are recorded in `.ai-ops-manifest.json`
+Deprecated old model 문맥에서만 유지되는 항목:
 
-Skill authoring rules live in `apps/cli/data/skills/README.md`.
+- `--project`는 project scope skill 설치용 old option입니다.
+- `--global`, `--scope`는 skill scope를 직접 지정하던 old option입니다.
+- `spec init`은 root `specs/`를 만들던 제거된 old command입니다.
+- `.ai-ops-manifest.json`는 old project manifest입니다.
 
-## Local Development
+## 개발
 
-From repo root:
+저장소 루트 기준:
 
 ```bash
 npm install
@@ -168,57 +153,18 @@ npm run compile
 npm test
 ```
 
-From `apps/cli` workspace:
+CLI workspace만 확인할 때:
 
 ```bash
 npm run build --workspace=apps/cli
 npm run test --workspace=apps/cli
 ```
 
-## Local Skill Loading Check
-
-Use the built-in `skill-load-check` task skill before publishing to npm.
-
-Recommended local flow:
-
-```bash
-# 1. Build the CLI
-npm run build
-
-# 2. Use an isolated user home so you do not pollute your real ~/.agents or ~/.claude
-export AI_OPS_HOME="$(mktemp -d)"
-
-# 3. Install the sample skill globally
-node apps/cli/dist/bin/index.js skill install skill-load-check --tool codex
-
-# 4. Verify files exist
-find "$AI_OPS_HOME/.agents/skills/skill-load-check" -maxdepth 2 -type f | sort
-
-# 5. Run the sample script manually
-node "$AI_OPS_HOME/.agents/skills/skill-load-check/scripts/loaded.js"
-```
-
-Expected output:
-
-```text
-A Skill loaded
-```
-
-Project-scope verification:
-
-```bash
-node apps/cli/dist/bin/index.js skill install skill-load-check --project --tool codex
-find ./.agents/skills/skill-load-check -maxdepth 2 -type f | sort
-node ./.agents/skills/skill-load-check/scripts/loaded.js
-```
-
-After file placement is verified, use a real tool prompt that should trigger `skill-load-check` and confirm the tool discovers the skill metadata. If the tool caches skill discovery, restart that tool session before re-checking.
-
-## Related Docs
+코드와 운영 문서 변경은 `npm run check`를 기본 검증으로 사용합니다. CLI 배포 산출물 확인은 `npm run build`와 `npm run compile`을 함께 사용합니다.
 
-- Master blueprint: [`docs/plan.md`](../../docs/plan.md)
-- Implementation playbook: [`docs/implementation-playbook.md`](../../docs/implementation-playbook.md)
+Self-dogfood 검증은 `npm run build` 후 이 repo에 `init --tool codex --tool gemini --tool claude-code`를 적용하고, `diff`, `audit`, `update --force`, `uninstall --yes`, 재-`init`, 재-`audit` 순서로 확인합니다. 이 repo에는 `spec-lifecycle` pack을 설치하지 않고 `pack list`에서 `not installed` 상태만 확인합니다.
 
-## License
+## 관련 문서
 
-MIT
+- [Master blueprint](../../docs/plan.md)
+- [Implementation playbook](../../docs/implementation-playbook.md)

package/data/context-layer/AGENTS.md

@@ -0,0 +1,29 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+update_when:
+  - operating_layer_changes
+---
+# Agent Operating Layer
+
+이 파일은 이 프로젝트의 canonical agent entrypoint다. 도구별 adapter가 있더라도 운영 판단은 이 파일과 `docs/agent/*` 문서를 기준으로 한다.
+
+## 읽기 순서
+
+1. `AGENTS.md`
+2. `docs/agent/workflow.md`
+3. `docs/agent/rules/*.md`
+4. 작업 성격에 맞는 `docs/agent/checks/*.md`
+5. `docs/docs-status.md`
+
+## 문서 신뢰도
+
+- `Active`: 현재 판단 근거로 사용할 수 있다.
+- `Reserved`: 자리만 만든 문서다. 프로젝트가 보강하기 전까지 현재 판단 근거로 사용하지 않는다.
+- `Draft`: 작성 중인 문서다. 사용 전 검토가 필요하다.
+- `Archived`: 과거 기록이다. 현재 운영 판단에 사용하지 않는다.
+
+문서 상태가 애매하면 `docs/docs-status.md`와 각 문서 frontmatter를 함께 확인한다.

package/data/context-layer/CLAUDE.md

@@ -0,0 +1,14 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+update_when:
+  - adapter_changes
+---
+# Claude Code Adapter
+
+이 파일은 Claude Code가 프로젝트 운영 계층을 찾기 위한 adapter다.
+
+작업 전 `AGENTS.md`를 canonical entrypoint로 읽고, 세부 운영 문서는 `docs/agent/*`와 `docs/docs-status.md`를 따른다. 이 파일에는 중복 운영 규칙을 추가하지 않는다.

package/data/context-layer/GEMINI.md

@@ -0,0 +1,14 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+update_when:
+  - adapter_changes
+---
+# Gemini CLI Adapter
+
+이 파일은 Gemini CLI가 프로젝트 운영 계층을 찾기 위한 adapter다.
+
+작업 전 `AGENTS.md`를 canonical entrypoint로 읽고, 세부 운영 문서는 `docs/agent/*`와 `docs/docs-status.md`를 따른다. 이 파일에는 중복 운영 규칙을 추가하지 않는다.

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

@@ -0,0 +1,16 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_finish
+update_when:
+  - checklist_changes
+---
+# Impact Checklist
+
+- 공개 CLI 표면이 바뀌었는가?
+- 상태 파일 schema나 경로가 바뀌었는가?
+- 기존 사용자 파일 보존 정책에 영향이 있는가?
+- update/diff/uninstall 동작이 서로 같은 추적 기준을 쓰는가?
+- 실패 시 사용자가 복구할 수 있는 메시지를 받는가?

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

@@ -0,0 +1,17 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - review
+  - before_finish
+update_when:
+  - checklist_changes
+---
+# Review Checklist
+
+- 계획 문서의 의도와 실제 diff가 어긋나는 지점이 있는가?
+- 테스트가 잡지 못하는 런타임 회귀 위험이 있는가?
+- create-only 파일과 managed section 파일의 보존 정책이 섞이지 않았는가?
+- manifest, context-layer, 실제 파일 상태가 같은 기준으로 갱신되는가?
+- 검증 명령이 변경 범위에 충분히 직접적인가?

package/data/context-layer/docs/agent/maps/codebase-map.md

@@ -0,0 +1,16 @@
+---
+status: Reserved
+layer: agent
+owner: project
+read_when:
+  - codebase_navigation
+update_when:
+  - architecture_changes
+---
+# Codebase Map
+
+이 문서는 Reserved 상태입니다. 프로젝트가 실제 구조를 보강하기 전까지 현재 판단 근거로 사용하지 마세요.
+
+## 주요 영역
+
+- TBD

package/data/context-layer/docs/agent/rules/doc-update-rules.md

@@ -0,0 +1,22 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - document_change
+update_when:
+  - document_policy_changes
+---
+# Document Update Rules
+
+## 갱신 기준
+
+- 구현 동작이 바뀌면 해당 동작을 설명하는 `Active` 문서를 갱신한다.
+- 문서 상태/frontmatter 관리는 모든 Markdown이 아니라 context-layer와 `docs/docs-status.md`에 등록된 operating-layer 문서를 기준으로 한다.
+- `Reserved` 문서를 실제 판단 근거로 승격하려면 frontmatter와 `docs/docs-status.md`를 함께 갱신한다.
+- 오래된 문서는 삭제보다 `Archived` 전환을 우선 검토한다.
+
+## 금지
+
+- project-owned create-only 문서를 자동 update로 덮어쓰지 않는다.
+- 도구 adapter에 canonical 운영 규칙을 중복 작성하지 않는다.

package/data/context-layer/docs/agent/rules/routing-rules.md

@@ -0,0 +1,22 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+update_when:
+  - routing_changes
+---
+# Routing Rules
+
+## 판단 순서
+
+1. 요청이 코드 변경인지, 리뷰인지, 문서 정리인지 구분한다.
+2. repo 내부의 계획 문서가 지정되면 실제 diff와 직접 비교한다.
+3. 외부 사실이나 최신 정보가 필요한 경우 현재 출처를 확인한다.
+4. 프로젝트 문서가 `Reserved`이면 현재 사실로 인용하지 않는다.
+
+## 범위
+
+- project scope: `AGENTS.md`, `GEMINI.md`, `CLAUDE.md`, `docs/agent/*`, `docs/business/*`, `docs/docs-status.md`, `.ai-ops/*`
+- global scope: skills, subagents, tool-specific reusable assets