ai-ops-cli 1.4.1 → 1.5.1

package/README.ko.md

@@ -74,19 +74,19 @@ receipts/config/*
 
 `AGENTS.md`, `GEMINI.md`, `CLAUDE.md`, `docs/agent/rules/*`, `docs/agent/checks/impact-checklist.md`, `docs/agent/workflow.md`는 ai-ops managed 문서입니다. 이 파일의 `<!-- ai-ops:start -->`부터 `<!-- ai-ops:end -->`까지는 CLI 템플릿 영역이고, `ai-ops update` 때 현재 CLI 템플릿으로 다시 적용됩니다. 사용자가 이 영역을 직접 수정하면 다음 update에서 유지되지 않습니다.
 
+`docs/agent/project-rules/*.md`는 project-owned 영역이며 `ai-ops update --force`가 내용을 덮어쓰지 않습니다.
+
 `.ai-ops/manifest.json`과 `.ai-ops/context-layer.json`도 직접 편집 대상이 아닙니다. 각각 설치 상태와 문서 index를 기록하는 CLI 상태 파일입니다.
 
 ### 사용자가 직접 수정해야 하는 파일은 무엇인가요?
 
-프로젝트 지식은 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가 자동으로 덮어쓰지 않습니다.
+프로젝트 지식은 project-owned 문서에 적습니다. 기본 project-owned 문서는 `docs/agent/maps/codebase-map.md`, `docs/business/terminology.md`, `docs/business/business-rules.md`, `docs/docs-status.md`입니다. 프로젝트 고유 agent 행동 규칙은 `docs/agent/project-rules/*.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 기준으로 테이블이 정리될 수 있습니다.
 
 ### 프로젝트 고유 agent rule은 어디에 적나요?
 
-현재 기본 layer에는 프로젝트 구조와 비즈니스 규칙을 담는 project-owned 문서가 있지만, 프로젝트별 agent 행동 규칙만을 위한 별도 Active 문서는 아직 first-class 템플릿으로 열려 있지 않습니다. 그래서 `AGENTS.md`의 managed 영역이나 tool adapter에 직접 규칙을 추가하는 방식은 update-safe한 계약이 아닙니다.
-
-프로젝트별 agent rule을 안정적으로 지원하려면 `docs/agent/rules/project-rules.md` 같은 project-owned Active 문서를 추가하고, manifest/context-layer/docs-status가 함께 추적하도록 제품 계약을 확장하는 것이 다음 개선 후보입니다.
+`docs/agent/project-rules/*.md`를 사용합니다. 이 디렉터리의 Markdown은 유효한 operating-layer frontmatter가 있으면 project-owned context 문서로 발견됩니다. `ai-ops update`, `diff`, `audit`는 이를 `.ai-ops/manifest.json`, `.ai-ops/context-layer.json`, `docs/docs-status.md`에 반영하고 forced update에서도 내용을 보존합니다.
 
 ## 목표 CLI 표면
 
@@ -167,7 +167,7 @@ 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은 설치하지 않습니다.
+`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 project root 아래 `.codex/plans`에는 write를 허용하고, `.git`은 read-only로 두며 `**/*.env` read는 차단합니다. `PermissionRequest` hook이나 command allow rule은 설치하지 않습니다.
 
 ai-coding worker에서는 Codex subprocess를 run-scoped로 실행하고, commit/push/PR 생성은 orchestrator가 담당하게 합니다.
 
@@ -180,10 +180,10 @@ 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.filesystem.":project_roots"."."="write"' \
+  -c 'permissions.ai-worker-impl.filesystem.":project_roots".".git"="read"' \
+  -c 'permissions.ai-worker-impl.filesystem.":project_roots".".codex/plans"="write"' \
+  -c 'permissions.ai-worker-impl.filesystem.":project_roots"."**/*.env"="none"' \
   -c 'permissions.ai-worker-impl.network.enabled=false'
 ```
 

package/README.md

@@ -74,19 +74,19 @@ receipts/config/*
 
 `AGENTS.md`, `GEMINI.md`, `CLAUDE.md`, `docs/agent/rules/*`, `docs/agent/checks/impact-checklist.md`, and `docs/agent/workflow.md` are ai-ops managed documents. In these files, the region from `<!-- ai-ops:start -->` through `<!-- ai-ops:end -->` is CLI template content. `ai-ops update` reapplies the current CLI template to that region. User edits inside that region are not preserved across update.
 
+`docs/agent/project-rules/*.md` is project-owned and is not overwritten by `ai-ops update --force`.
+
 `.ai-ops/manifest.json` and `.ai-ops/context-layer.json` are also not direct-edit files. They are CLI state files for installation state and document indexing.
 
 ### 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/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.
+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`. Project-specific agent behavior rules belong in `docs/agent/project-rules/*.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.
 
 ### Where should project-specific agent rules go?
 
-The default layer currently has project-owned documents for project structure and business rules, but it does not yet provide a first-class Active template for project-specific agent behavior rules. Because of that, adding rules inside the managed region of `AGENTS.md` or inside a tool adapter is not an update-safe contract.
-
-To support project-specific agent rules safely, the next product extension should add a project-owned Active document such as `docs/agent/rules/project-rules.md` and have the manifest, context-layer index, and docs-status table track it together.
+Use `docs/agent/project-rules/*.md`. Files in this directory are project-owned context documents when they have valid operating-layer frontmatter. `ai-ops update`, `diff`, and `audit` discover them, track them in `.ai-ops/manifest.json`, `.ai-ops/context-layer.json`, and `docs/docs-status.md`, and preserve their content across forced updates.
 
 ## CLI Surface
 
@@ -167,7 +167,7 @@ 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.
+`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 project roots while keeping `.git` read-only and blocking `**/*.env` reads. 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:
 
@@ -180,10 +180,10 @@ 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.filesystem.":project_roots"."."="write"' \
+  -c 'permissions.ai-worker-impl.filesystem.":project_roots".".git"="read"' \
+  -c 'permissions.ai-worker-impl.filesystem.":project_roots".".codex/plans"="write"' \
+  -c 'permissions.ai-worker-impl.filesystem.":project_roots"."**/*.env"="none"' \
   -c 'permissions.ai-worker-impl.network.enabled=false'
 ```
 

package/data/context-layer/AGENTS.md

@@ -18,8 +18,9 @@ update_when:
 3. `docs/agent/workflow.md`
 4. `docs/agent/terminology.md`
 5. 나머지 `docs/agent/rules/*.md`
-6. 변경 영향 확인이 필요하면 `docs/agent/checks/impact-checklist.md`
-7. `docs/docs-status.md`
+6. 프로젝트가 보강한 `docs/agent/project-rules/*.md`
+7. 변경 영향 확인이 필요하면 `docs/agent/checks/impact-checklist.md`
+8. `docs/docs-status.md`
 
 ## 문서 신뢰도
 

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

@@ -15,6 +15,7 @@ update_when:
 - 문서 상태/frontmatter 관리는 모든 Markdown이 아니라 context-layer와 `docs/docs-status.md`에 등록된 operating-layer 문서를 기준으로 한다.
 - `Reserved` 문서를 실제 판단 근거로 승격하려면 frontmatter와 `docs/docs-status.md`를 함께 갱신한다.
 - 오래된 문서는 삭제보다 `Archived` 전환을 우선 검토한다.
+- `docs/agent/project-rules/*.md`를 추가/수정할 때는 기존 `Active` agent rules와의 중복, 충돌 가능성, 적용 우선순위/조건을 함께 검토하고 필요한 경우 문서에 명시한다.
 
 ## 금지
 

package/data/context-layer/docs/agent/workflow.md

@@ -32,6 +32,14 @@ update_when:
 - project-owned 문서가 비어 있거나 stale하면 실제 코드, 설정, schema, runtime 파일을 우선한다.
 - 문서 상태가 애매하면 `docs/docs-status.md`와 각 문서 frontmatter를 함께 확인한다.
 
+## Reference-Backed Implementation
+
+reference 문서에 근거해 구현할 때는 문서의 핵심 제약을 먼저 검증 가능한 acceptance condition으로 바꾼다.
+
+- `must`, `required`, `top-level`, `cannot mix`, `does not compose` 같은 강제 제약은 그냥 읽고 넘어가지 않는다.
+- config, schema, parser, runtime이 직접 해석하는 구조와 permission, sandbox, credential, network, filesystem boundary는 테스트, fixture, smoke command, audit check 중 하나로 고정한다.
+- 문서의 중요한 문장을 테스트 이름으로 바꾼다.
+
 ## 보존 원칙
 
 - 사용자 변경으로 보이는 diff는 되돌리지 않는다.