# coding-ethos - Doramagic AI Context Pack

> 定位：给用户宿主 AI 装载的开工前上下文。它不代表已经安装、运行或验证目标项目。

## 项目

- canonical_name: `paudley/coding-ethos`
- capability: Policy-as-code enforcement for AI agents: MCP server, CEL policies, git hooks, SARIF, and static analysis guardrails.
- expected_user_outcome: Policy-as-code enforcement for AI agents: MCP server, CEL policies, git hooks, SARIF, and static analysis guardrails.

## 基础边界

- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。
- 项目事实必须来自 repo evidence、Claim Graph 或明确来源。
- 遇到未验证能力时，必须标记为待验证，而不是补全为事实。
- publish_status: `publishable`
- blocking_gaps: none

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **项目概述**：importance `high`
  - source_paths: README.md, ETHOS.md, coding_ethos.yml
- **快速开始**：importance `high`
  - source_paths: Makefile, CLAUDE.md, AGENTS.md, GEMINI.md
- **系统架构**：importance `high`
  - source_paths: docs/AST_CEL_SARIF_ARCHITECTURE.md, go/cmd/coding-ethos-run/main.go, go/internal/hookrunnercli/main.go, coding_ethos/CODING_ETHOS.md
- **核心组件**：importance `medium`
  - source_paths: go/cmd/coding-ethos-policy/main.go, go/cmd/coding-ethos-mcp/main.go, go/cmd/coding-ethos-lint/main.go, go/cmd/coding-ethos-git/main.go
- **策略引擎**：importance `high`
  - source_paths: go/internal/policy/compiler.go, go/internal/policy/bundle.go, go/internal/policy/decision.go, go/internal/evaluators/evaluator.go
- **CEL策略表达式**：importance `medium`
  - source_paths: go/internal/celexpr/inputs.go, go/internal/celexpr/lint.go, go/internal/celexpr/tool_capability.go, POLICY_COMPILER.md

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: false
- repo_inspection_verified: false
- repo_commit: `unknown`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 失败模式：installation: Bundle or provision Bubblewrap as a required sandbox dependency

- Trigger: Developers should check this installation risk before relying on the project: Bundle or provision Bubblewrap as a required sandbox dependency
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Bundle or provision Bubblewrap as a required sandbox dependency. Context: Observed during installation or first-run setup.
- Why it matters: Developers may fail before the first successful local run: Bundle or provision Bubblewrap as a required sandbox dependency
- Evidence: failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/132 | Bundle or provision Bubblewrap as a required sandbox dependency
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 失败模式：installation: bug: commit amend is not blocked by git safety policy

- Trigger: Developers should check this installation risk before relying on the project: bug: commit amend is not blocked by git safety policy
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: bug: commit amend is not blocked by git safety policy. Context: Observed during installation or first-run setup.
- Why it matters: Developers may fail before the first successful local run: bug: commit amend is not blocked by git safety policy
- Evidence: failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/112 | bug: commit amend is not blocked by git safety policy
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 来源证据：Bundle or provision Bubblewrap as a required sandbox dependency

- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bundle or provision Bubblewrap as a required sandbox dependency
- Why it matters: 可能增加新用户试用和生产接入成本。
- Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/132 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 来源证据：bug: commit amend is not blocked by git safety policy

- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: commit amend is not blocked by git safety policy
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/112 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: 失败模式：configuration: [feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping

- Trigger: Developers should check this configuration risk before relying on the project: [feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping. Context: Observed when using python
- Why it matters: Developers may misconfigure credentials, environment, or host setup: [feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping
- Evidence: failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/54 | [feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 失败模式：configuration: [test] Add sandbox workflow E2E coverage

- Trigger: Developers should check this configuration risk before relying on the project: [test] Add sandbox workflow E2E coverage
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [test] Add sandbox workflow E2E coverage. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may misconfigure credentials, environment, or host setup: [test] Add sandbox workflow E2E coverage
- Evidence: failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/129 | [test] Add sandbox workflow E2E coverage
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 来源证据：[test] Add real MCP stdio workflow coverage

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[test] Add real MCP stdio workflow coverage
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能增加新用户试用和生产接入成本。
- Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/114 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 能力判断依赖假设

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: 将假设转成下游验证清单。
- Why it matters: 假设不成立时，用户拿不到承诺的能力。
- Evidence: capability.assumptions | github_repo:1214781313 | https://github.com/paudley/coding-ethos | README/documentation is current enough for a first validation pass.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 9: 失败模式：runtime: [feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation

- Trigger: Developers should check this runtime risk before relying on the project: [feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation. Context: Observed when using python
- Why it matters: Developers may hit a documented source-backed failure mode: [feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation
- Evidence: failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/55 | [feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 维护活跃度未知

- Trigger: 未记录 last_activity_observed。
- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Evidence: evidence.maintainer_signals | github_repo:1214781313 | https://github.com/paudley/coding-ethos | last_activity_observed missing
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。