框架总览与器官架构

1. 核心命题：把"输出"变成"假设"

Verel 的全部设计可以浓缩为一句话——"an agent's output is a *hypothesis* until a grader returns a verdict"：智能体的输出在被评分器给出判定之前，都只是一个待检验的假设。整个框架的目标就是把所有"检查"（测试、类型、lint、视觉、性能、安全）统一成同一种 pass / warn / fail，并只让通过校验的工作才能沉淀进记忆。

资料来源：src/verel/README.md:1-15

模块级 README 直接以"unifies every check … into one pass / warn / fail, and only verified work is allowed to compound into memory"作为论点摘要，并配以一个最小可运行示例——用 verel.verdict 包的 gate() 与 assign() 即可在 6 行内演示闸门行为。

资料来源：src/verel/README.md:15-25

2. 器官全景与导入约定

src/verel/README.md 在 "The six organs at a glance" 表格中给出了模块到器官的映射。下面是该表可被验证的片段（含前两行明确可见，其余器官按源码导入点交叉确认）：

资料来源：src/verel/README.md:25-35、src/verel/memory/__init__.py:1-25、src/verel/ci/__init__.py:1-15

器官之间不是分层调用关系，而是事件总线型：senses 产出 Report，verdict.gate() 做出放行/阻断决策，memory 才是写回长期记忆的唯一通道，agents 在闸门被拒时介入修复。

3. 数据流：感知→门控→记忆→修订

下图描述一次完整闭环——一个智能体动作如何穿过所有器官，最终在 memory 中留下可被 recall 的痕迹：

flowchart LR
    A[Agent action] --> B[senses<br/>sight/sight.py]
    B -->|list[Report]| C{verdict.gate<br/>required: GraderKind}
    C -->|PASS / WARN| D[memory.write<br/>candidate]
    C -->|FAIL| E[agents.coder<br/>make_fix_hook]
    E -->|patch| A
    D --> F[consolidate + librarian]
    F -->|counterexample?| G[revise.revise_with_counterexample]
    G -->|narrow / split / reject| D
    D --> H[recall via MCP<br/>verel_recall]

关键不变量：

资料来源：src/verel/memory/local.py:1-35

资料来源：src/verel/memory/consolidate.py:1-25

资料来源：src/verel/memory/revise.py:1-50

• 同 key 合并：LocalMemory.write 规定 same (subject, predicate, scope) 触发 supersede，重复声明只增加 support_count 与 epistemic_confidence，从不复制记录。
• 永不自动 verified：consolidation 与 graduation 都只写 trust=candidate；信任只能通过相互佐证或 held-out 评估获得。
• 可被反例击穿：revise_with_counterexample 在同类失败累计到阈值（默认 2）后，会让 LLM 把过宽规则 *split* 为 narrowed + exception，narrowed 通过 subj_pred_key 原地覆盖原规则。

4. 社区聚焦的能力缺口

仓库当前最热的几个 issue 都集中在器官交界处的可用性细节，值得在阅读本总览后顺藤摸瓜：

资料来源：src/verel/ci/graders.py:1-40

资料来源：src/verel/ci/graders.py:30-45

• 多仓 monorepo 门控（#4）：需要在 verdict.gate 之上叠加"按子包 stage"的能力，但 docs/usage.md 还没有对应菜谱。
• 评分器解析器的真实样本覆盖（#3）：ci/graders.py 中的纯函数解析器（pytest/ruff/mypy/eslint/tsc/go-test/go-vet/bandit/npm-audit/perf）目前只用罐头样本测试，需要更真实的工具输出。
• verel doctor 信息密度（#2）：CLI 体检命令应同时报告"已安装 extras"与"已就位的 provider keys"。
• Rust 工具链接入（#1）：希望仿照 LANGS["python"|"js"|"go"] 的 LangToolchain 模式新增 cargo test + clippy。

近 7 个 release 都在强化器官间的安全与可验证边界：v0.30.0 引入 ed25519 公开可验证的 receipt；v0.31.0–v0.32.0 把 Memory 升级为多主体共享脑并加上身份认证；v0.34.0 通过 verdict.fact_commitment 把 verified 等级绑定到具体事实；v0.35.0 让 MCP 工具可读写远程认证脑；v0.36.0 在所有非 loopback 绑定上引入共享 verel.transport TLS 模块。这些里程碑共同指向一条主线——所有器官都必须默认 fail-closed。

See Also

• Verdict 契约（verel.verdict）与 gate() 的判定策略
• 记忆模型与信任等级（verel.memory）
• 语言工具链与评分器（verel.ci.graders）
• MCP 验证子协议（verel_recall / verel_verify / verel_attest）
• 多主体共享脑与 v0.32.0 之后的认证模型

目的与范围

Verel 的核心论点是：智能体（agent）的输出在被评分器（grader）给出判定之前只是一个假设。判决总线（Verdict Bus）是统一所有检验的契约层 —— 测试、类型检查、Lint、视觉、性能、安全 —— 任何"感官"产出的 Report 都被归约为统一的 pass / warn / fail，并通过 gate() 函数收敛成可执行决策。CI/CD 评分器则是该总线在工程实践中的具体载体：以子进程方式运行真实的工具链（pytest、ruff、mypy、eslint、tsc、go test、go vet、bandit、npm audit、perf 等），解析 (stdout, stderr)，再把结果送回总线。

flowchart LR
    Tools["工具链<br/>pytest / ruff / mypy / eslint<br/>tsc / go test / go vet<br/>bandit / npm audit / perf"] --> Parsers["纯函数解析器<br/>parse_pytest / parse_mypy / ..." ]
    Parsers --> Reports["Report + Issue<br/>(统一契约)"]
    Sight["感知器官<br/>AgentVision (sight)"] --> Reports
    Reports --> Gate["gate()<br/>advisory ceiling + 证明 + 进度"]
    Gate --> StageResult["StageResult<br/>verdict / 失败集合"]
    StageResult --> Receipt["sign_receipt()<br/>(ed25519 证明)"]
    StageResult --> Ledger["FailureLedger<br/>(防回归)"]

数据模型：Verdict Bus 的统一契约

Report / Issue / Percept / RunReceipt / GateResult 在 src/verel/verdict/models.py 中定义；verdict 包通过 __init__.py 将这些符号统一暴露：

• Verdict 三态：PASS / WARN / FAIL；
• Severity 四级：INFO / WARNING / ERROR / CRITICAL，其顺序在 src/verel/verdict/constants.py 的 SEV_ORDER 中固定（索引 = 等级），后续的夹紧（clamp）与归约都依赖这一稳定顺序；
• GraderKind 枚举涵盖 TEST / TYPECHECK / LINT / DOM / OCR / CV / SECURITY / DSP / ASR / VISION / LLM_JUDGE / ACOUSTIC / AUDIO_LLM 等来源；
• Issue.source 直接对应 GraderKind，让每个 Issue 在归约时都能映射到其"接地"等级。

constants.py 中定义了两个关键集合：PRECISE_GRADERS（精确，可门控：TEST / TYPECHECK / LINT / DOM / OCR / CV / SECURITY / DSP / ASR）与 ADVISORY_GRADERS（咨询性：VISION / LLM_JUDGE / ACOUSTIC / AUDIO_LLM）。后者会被 gate() 自动夹紧到 ADVISORY_CEIL = Severity.WARNING，避免开放性的模型判断直接锁死流水线。

`gate()`：归约规则与可验证证明

gate()（定义于 src/verel/verdict/gate.py）承担三项不可妥协的规则：

为了让"另一方可验证"，sign_receipt() 使用 ed25519 对 Report 做签名，verify_signature() 进行回验；v0.30.0 之后的版本还引入了 fact_commitment(subject, predicate, text) 等事实绑定证明（v0.34.0 release notes），让跨主体的"verified"等级只能由绑定到事实的证明获得 —— 信任不靠口头传递。指纹层（fingerprint.py）通过 assign() 与 issue_signature() 在归一化（行号、地址、浮点）后生成稳定的 Issue 指纹，确保跨进程、跨主体的去重与回放可靠。

CI/CD 评分器与流水线阶段

verel.ci 把上述契约工程化。graders.py 暴露一组工具链无关的纯函数解析器：每个 parse_* 都接受 (stdout, stderr) 并返回 list[Issue]；每种语言绑定一个 *_spec 工厂，把命令、cwd、covers、解析器、lang 打包成 GraderSpec。ci/__init__.py 同时导出 pytest_spec / ruff_spec / mypy_spec / eslint_spec / tsc_spec / jstest_spec / gotest_spec / govet_spec / bandit_spec / npm_audit_spec / perf_spec，以及一个统一的 run_grader(GraderSpec, runner=subprocess_runner)。

pipeline.py 把评分器组合成阶段（Stage）：

• inner_loop_stage、precommit_stage、premerge_stage、postmerge_stage 对应不同生命周期的门控；
• Stage 包含 graders: list[GraderSpec] 与 required: set[GraderKind]，后者即 gate() 用于证明检查的必备集合；
• run_stage() 调用 gate(reports, required=...)，产出 StageResult(verdict, gate, reports, regressions)；其中 regressions 来自 src/verel/memory/failure_ledger.py —— 一旦发现曾被修复过的失败再次出现，即使工具链静默也会被记为回归。

SightResult（src/verel/senses/sight.py）通过 _SOURCE_TO_GRADER 把 AgentVision 的 dom / ocr / cv / vision 映射到 GraderKind.DOM/OCR/CV/VISION，从而让"看"作为一等公民进入同一总线 —— 视觉感受如果触发了 WARN，仍然可能因"咨询上限"而无法单独 FAIL 流水线。

常见失效模式与社区关切

• 测试覆盖盲区：社区 Issue #3 指出 tests/test_ci_senses.py 中的"罐头样本"覆盖面不足，建议加入更多真实工具输出。
• 新增语言工具链：Issue #1 要求按 graders.py 既有模式补上 parse_cargo_test / parse_clippy 等 Rust 评分器。
• Monorepo 编排：Issue #4 指出 docs/usage.md 尚未给出"按包独立阶段"的范例；可基于 inner_loop_stage 在每个子包路径上重复 run_stage(Stage(name=pkg_a, ...))。
• 环境可观测性：Issue #2 提议 verel doctor 列出已安装的可选 extras 与提供方密钥，这会直接影响"评分器是否真的能跑"（例如 npm audit 缺 Node、bandit 缺 bandit 等）。

排错时建议先确认：(1) 解析器是否识别了目标工具链的输出格式；(2) required 集合是否漏配导致空心 gate；(3) PRECISE_GRADERS 中的项是否被误标为 ADVISORY_GRADERS；(4) progressed() 是否能在最近 W = 4 窗口内看到失败集合严格收缩。

See Also

• 感知器官与 AgentVision
• 共享验证记忆（Brain）
• 开发指南 Cookbook
• Release v0.34.0 — fact-bound attestation

概述与设计理念

Verel 的 "Brain" 是 verel.memory 包实现的带信任的长期记忆层，是六大器官（verdict / senses / memory / fleet / toolsmith / ci / registry）之一。Brain 的核心论点来自项目根 README.md：只有经过验证的工作才能沉淀到记忆中，记忆系统不仅是存取接口，更是一道"信任闸门"。

Brain 围绕三个递进的属性演化（亦对应三次发布里程碑）：

1. 共享（v0.31.0 – v0.32.0） —— 多台机器/多个操作者共用一个统一后台；
2. 验证（v0.34.0） —— 跨主体的信任只能通过"事实绑定"的 attestation 取得，verified 等级不能由"说法"获得；
3. 高可用与机密传输（v0.36.0） —— 通过复制与 TLS 实现可路由的 brain、lease、registry 三服务。

资料来源：README.md

核心数据模型

Brain 的基本对象是 MemoryRecord 与 MemoryView 接口。view.py 定义了内容寻址的记录结构与五种 MemoryKind：

__init__.py 暴露了主要入口：LocalMemory、ReplicatedMemory、MemoryView、PromotionGate、HeldOutCorpus、AuthorTrust 等。local.py 的 LocalMemory.write 还明确实现了一条写入干扰规则：相同的归一化文本视为"再佐证"——置信度 +0.1 且不复制（最高封顶 1.0）。

资料来源：src/verel/memory/__init__.py, src/verel/memory/local.py

共享与多主体认证

作用域格（scope lattice）

verel_recall(query, scope, kind, k) 通过作用域格解析：DOWN 解析（self < team < org < global）。这是共享的语义基础：每个 agent 只能读到对自己可见的作用域，但写入可以"上行"到组织级甚至全局。lattice.py 负责把任意 scope 字符串解析为有序的祖先链。

资料来源：src/verel/memory/lattice.py, v0.31.0 release notes

签名写入与键隔离

principal.py 实现 ed25519 主体身份（v0.32.0）。客户端签名写入只允许 kind=FACT，并且不能落到保留的 (predicate, scope) 键上——这些键（author_trust、design_rule、schema、fails、tool）由服务端流水线管理，禁止客户端直接覆盖。文件里还设了 _MAX_TEXT=20_000 和 _MAX_FIELD=512 字段长度上限，防止签名写入撑爆后端存储。

资料来源：src/verel/memory/principal.py

跨主体信任与 AuthorTrust

share.py 实现 AuthorTrust：每个作者在 meta:authors 作用域下保留一个 Laplace 平滑的再验证率 prior(author) ∈ (0, 1)。import_belief 在导入外来信念时会查询作者声誉，信任不靠宣称——一个 peer 的 verified 等级必须由其他 agent 的再验证维持稳定（v0.32.0 closes deferred Findings 3 & 4）。

资料来源：src/verel/memory/share.py, v0.32.0 release notes

验证晋升路径

Brain 走的是双闸门晋升路径：

1. 支撑计数（corroborate）——相同声明反复出现则 support_count 递增，置信度 +0.1、检索强度重置为 1.0；不同文本则取代旧记录，累加 provenance。这条规则保证"再佐证"与"反驳"都能结构化落到记录上。

资料来源：src/verel/memory/local.py

1. 留出评估闸（PromotionGate）——promotion.py 持有一个人类持有、agent 不可访问的 HeldOutCorpus（带 canary_token 防止被自动抓取）。PROMOTE_F1 = 0.8 是晋升阈值；只有 F1 ≥ 阈值的候选规则才能从 candidate 升至 verified。evaluate_rule 在 importer 自己的上下文里跑这批用例，信任只在本地可验证时才移动。

资料来源：src/verel/memory/promotion.py

反之，反例通过 revise.py 触发修订（revise_with_counterexample）：先 annotate 后 contradict，置信度下降；累计 split_after 个反例后由 LLM 把过宽规则拆成更窄规则 + 例外规则——而修订只缩窄作用域、永不自动 verified。consolidate.py 则是反方向的"生长"路径：把 episodic failures 聚簇为 DESIGN_RULE、再聚为 SCHEMA，但每一步都只写 trust=candidate，从不自我验证。

资料来源：src/verel/memory/revise.py, src/verel/memory/consolidate.py

v0.34.0 进一步收紧：跨主体 verified 等级只能由 verdict.fact_commitment(subject, predicate, text) 授予——一份 256 字节的事实绑定 attestation，签名不等于验证。

资料来源：v0.34.0 release notes

高可用与机密传输

复制与 Anti-Entropy

__init__.py 同时暴露了 ReplicatedMemory、NotLeaderError、ReplicationError、ReplicationStatus、AntiEntropy。Brain 通过独立的租约授权（lease authority，位于 verel.lease）选举 leader，follower 通过 anti-entropy 周期对账；leader 崩溃时 NotLeaderError 触发自动选主，写可用与读可用分离。README.md 中的 demo_shared_brain.py 演示了"不可下毒 / HA / 崩溃容忍"的端到端行为。

资料来源：src/verel/memory/__init__.py, src/verel/memory/replicate.py, README.md

TLS 化绑定（v0.36.0）

v0.36.0 引入统一 verel.transport 模块：brain / lease / registry 三个 HTTP 服务共享同一套 TLS 配置。MemoryServer 接受 certfile=/keyfile=/ssl_context= 参数，url 报告 https://，最低 TLS 1.2，非回环绑定 fail-closed，回环仍零配置。配合 v0.35.0 的 VEREL_BRAIN_URL 环境变量，agent 可以把 verel_recall / verel_remember 路由到远端认证脑，让分布在不同机器上的 fleet 共享同一份带信任的记忆。

资料来源：v0.35.0 release notes, v0.36.0 release notes, src/verel/memory/hosted.py

常见失败模式

• 直接覆盖保留键：客户端若把 (subject="x", predicate="design_rule", scope="…") 这种保留键以 FACT 形式签名写入，会被 principal.py 拒收——这是设计而非 bug。
• 置信度漂移：revise.py 在 contradict 时以固定步长降低置信度；如果反例来源不可信，需要在 AuthorTrust.record 里把"未通过"的样本同步记入作者声誉。
• 回环到非回环的迁移：在 v0.36.0 下若把 brain 绑到 0.0.0.0 但忘了配证书，server 端会直接拒绝启动；这是 fail-closed 的预期行为，需先准备好 certfile/keyfile。

小结

Brain 不是一个普通 KV：它把作用域格、签名写入、AuthorTrust、留出评估闸、反例修订、复制抗熵、TLS 绑定七层控制堆叠在一起，让"经验"能跨进程、跨机器、跨主体地安全传递。从 v0.31.0 的"共享骨架"到 v0.36.0 的"加密通道"，Brain 的演进主线一直是同一句话——信任不靠宣称，验证只通过事实。

See Also

• Verdict 总线：统一评估契约
• CI 子系统：自愈与评分
• Skill Registry：签名技能分发

概述与目标

Verel 的 "Fleet 编排、Toolsmith 与部署运维" 主题把三件互相耦合的事打包在一起：多 worker 协同的 Fleet 编排、面向 agent 的 Toolsmith（技能）注册与复用、以及面向生产的 CLI、CI、MCP 与传输层安全。这些子系统共同支撑 Verel 的核心论点——agent 的产出在 grader 返回 verdict 之前都只是 hypothesis（资料来源：README.md）。

CLI 表面是这一切的入口，它把六个器官串成可执行命令（资料来源：src/verel/README.md）：

verel doctor | loop | fleet | heal | ci
verel-ci check | precommit | install
verel-mcp          # 暴露 gate / recall / build_tool / ci_check 四个工具

Toolsmith：技能生命周期管理

Toolsmith 解决"agent 重复造轮子"的问题——它把 agent 生成的工具持久化为 MemoryKind.SKILL 记录，使后续会话可以按能力语义检索并复用（资料来源：src/verel/toolsmith/registry.py）。注册表的核心 API 是 find(capability, verified_only=True, k=3, min_relevance=0.0)，返回 ToolRecord 列表：

• 当底层记忆带有 embedder 时，查询走 cosine(query_vec, hit_vec) 语义相似度；
• 否则退化为词面 token-overlap 的 relevance() 启发式；
• 默认只暴露 Trust.VERIFIED 的工具，未验证的工具即使命中也被过滤。

写回路径上，Toolsmith 复用 MemoryView.write() 的干扰规则：相同 (subject, predicate, scope) 三元组会覆盖已有记录而不是产生副本（资料来源：src/verel/memory/local.py）。当新写入与旧记录文本一致时，support_count 自增、epistemic_confidence 上升（上限 1.0）、retrieval_strength 重置为 1.0，从而形成天然的去重 + 置信度累加机制。

多语言 CI 评测与 gate

部署前的最后一道闸门是 verel-ci，它把多语言工具链统一在一条 verdict bus 上。src/verel/ci/graders.py 用 LANGS: dict[str, LangToolchain] 注册了三条语言工具链（资料来源：src/verel/ci/graders.py）：

每个 GraderSpec 由 *命令行模板* + *parser* + lang 标签 组成；parser 是 (stdout, stderr) -> list[Issue] 的纯函数，因此可以独立用固定样例做回归测试。社区关注的 #1 添加 Rust 工具链 正是要按同一模式补上 parse_cargo_test / parse_clippy 并扩展 LANGS；#3 拓宽 parser 测试 则希望把 tests/test_ci_senses.py 中的样例替换为真实工具输出。

verel-ci 还支持 install 子命令把当前仓库注册为 git pre-commit hook（资料来源：src/verel/ci/__init__.py）。

部署运维：CLI、Doctor、MCP 与传输安全

部署维度的关注点集中在三处：

1. verel doctor 环境自检——社区 #2 提出应把"已安装的可选 extras"和"已配置的 provider 密钥"渲染成一张小表，让新人一眼看清当前能力面（资料来源：src/verel/cli.py）。
2. MCP 验证底座——verel-mcp 把 gate / recall / build_tool / ci_check 四个动词暴露给任意 agent；v0.35.0 起当 VEREL_BRAIN_URL 设置时，verel_recall / verel_remember 会打到远端带认证的 MemoryServer，多机集群共享一份记忆（资料来源：v0.35.0 release notes）。
3. 传输层 TLS——v0.36.0 引入共享的 verel.transport，MemoryServer / ControlPlaneServer / RegistryServer 三个 HTTP 服务在非 loopback bind 时强制 TLS 1.2+，loopback 保持零配置；url 报告会切换为 https://（资料来源：v0.36.0 release notes）。

skill 自身的分发也走"内容寻址 + 签名 + 不跨 origin 覆盖"的原则：PublicRegistry.publish() 会先调 artifact.verify() 校验签名，再以 content_hash 落盘；若该哈希已属于另一 origin 的发布者则抛 ValueError，避免被恶意复用（资料来源：src/verel/registry/store.py）。

失败自愈、记忆巩固与修订

运维无法回避失败。Verel 的 self_heal 把 gate 失败的 Report 喂给 LLMCoder，由它重写源文件并再次跑 gate（资料来源：src/verel/agents/coder.py）。make_fix_hook() 把 coder 包装成 FixHook，挂在 verel.loop.ultracode_loop 的 render → perceive → gate → fix → re-render 流水线上。

记忆层在后台做两件方向相反的事：

• 巩固 consolidate.py：把 episodic failure 聚类、归纳成 DESIGN_RULE，再跨规则聚成 SCHEMA；新记录一律 trust=candidate，从不自动 verify（资料来源：src/verel/memory/consolidate.py）。
• 修订 revise.py：当一条规则在自己 covers_kind 域内反复失败时，revise_with_counterexample() 先 contradict 拉低 confidence，累积到 split_after 后让 LLM 把规则 narrow 为更窄的 narrowed 规则 + 一条 exception 规则；narrowed 规则通过相同 subj_pred_key 覆盖原规则（资料来源：src/verel/memory/revise.py）。

视觉通道则由 senses/sight.py 把 AgentVision 的 dom / ocr / cv / vision 四类 issue 通过闭映射 _SOURCE_TO_GRADER 转到统一 GraderKind，避免在六器官之间出现能力漂移（资料来源：src/verel/senses/sight.py）。

See Also

• verdict 总线与 Issue 模型
• Toolsmith 工具注册与复用
• CI gate 与多语言 grader
• 共享脑、MCP 验证与传输安全
• 自愈、回滚与记忆修订

Pitfall Log / 踩坑日志

项目：amitpatole/verel

摘要：发现 25 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: verel doctor: report installed extras and key presence。

1. 安全/权限坑 · 失败模式：security_permissions: verel doctor: report installed extras and key presence

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: verel doctor: report installed extras and key presence
• 对用户的影响：Developers may expose sensitive permissions or credentials: verel doctor: report installed extras and key presence
• 证据：failure_mode_cluster:github_issue | https://github.com/amitpatole/verel/issues/2 | verel doctor: report installed extras and key presence

2. 安装坑 · 失败模式：installation: Add a Rust toolchain (cargo test + clippy) to the CI graders

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Add a Rust toolchain (cargo test + clippy) to the CI graders
• 对用户的影响：Developers may fail before the first successful local run: Add a Rust toolchain (cargo test + clippy) to the CI graders
• 证据：failure_mode_cluster:github_issue | https://github.com/amitpatole/verel/issues/1 | Add a Rust toolchain (cargo test + clippy) to the CI graders

3. 安装坑 · 失败模式：installation: v0.28.0 — quorum reads: a point read survives the leader being down

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.28.0 — quorum reads: a point read survives the leader being down
• 对用户的影响：Upgrade or migration may change expected behavior: v0.28.0 — quorum reads: a point read survives the leader being down
• 证据：failure_mode_cluster:github_release | https://github.com/amitpatole/verel/releases/tag/v0.28.0 | v0.28.0 — quorum reads: a point read survives the leader being down

4. 安装坑 · 失败模式：installation: v0.29.0 — security hardening: full attack-surface audit + red-team

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.29.0 — security hardening: full attack-surface audit + red-team
• 对用户的影响：Upgrade or migration may change expected behavior: v0.29.0 — security hardening: full attack-surface audit + red-team
• 证据：failure_mode_cluster:github_release | https://github.com/amitpatole/verel/releases/tag/v0.29.0 | v0.29.0 — security hardening: full attack-surface audit + red-team

5. 安装坑 · 失败模式：installation: v0.29.1 — security: 3-round adversarial red-team

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.29.1 — security: 3-round adversarial red-team
• 对用户的影响：Upgrade or migration may change expected behavior: v0.29.1 — security: 3-round adversarial red-team
• 证据：failure_mode_cluster:github_release | https://github.com/amitpatole/verel/releases/tag/v0.29.1 | v0.29.1 — security: 3-round adversarial red-team

6. 安装坑 · 失败模式：installation: v0.29.2 — CI fix for the v0.29.1 security release

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.29.2 — CI fix for the v0.29.1 security release
• 对用户的影响：Upgrade or migration may change expected behavior: v0.29.2 — CI fix for the v0.29.1 security release
• 证据：failure_mode_cluster:github_release | https://github.com/amitpatole/verel/releases/tag/v0.29.2 | v0.29.2 — CI fix for the v0.29.1 security release

7. 安装坑 · 失败模式：installation: v0.30.0 — the verification substrate

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.30.0 — the verification substrate
• 对用户的影响：Upgrade or migration may change expected behavior: v0.30.0 — the verification substrate
• 证据：failure_mode_cluster:github_release | https://github.com/amitpatole/verel/releases/tag/v0.30.0 | v0.30.0 — the verification substrate

8. 安装坑 · 失败模式：installation: v0.31.0 — the shared verified brain

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.31.0 — the shared verified brain
• 对用户的影响：Upgrade or migration may change expected behavior: v0.31.0 — the shared verified brain
• 证据：failure_mode_cluster:github_release | https://github.com/amitpatole/verel/releases/tag/v0.31.0 | v0.31.0 — the shared verified brain

9. 安装坑 · 失败模式：installation: v0.32.0 — the authenticated multi-principal brain

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.32.0 — the authenticated multi-principal brain
• 对用户的影响：Upgrade or migration may change expected behavior: v0.32.0 — the authenticated multi-principal brain
• 证据：failure_mode_cluster:github_release | https://github.com/amitpatole/verel/releases/tag/v0.32.0 | v0.32.0 — the authenticated multi-principal brain

10. 安装坑 · 失败模式：installation: v0.34.0 — cross-principal verified tier (fact-bound attestation)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.34.0 — cross-principal verified tier (fact-bound attestation)
• 对用户的影响：Upgrade or migration may change expected behavior: v0.34.0 — cross-principal verified tier (fact-bound attestation)
• 证据：failure_mode_cluster:github_release | https://github.com/amitpatole/verel/releases/tag/v0.34.0 | v0.34.0 — cross-principal verified tier (fact-bound attestation)

11. 安装坑 · 失败模式：installation: v0.35.0 — MCP recall/remember over a remote authenticated brain

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.35.0 — MCP recall/remember over a remote authenticated brain
• 对用户的影响：Upgrade or migration may change expected behavior: v0.35.0 — MCP recall/remember over a remote authenticated brain
• 证据：failure_mode_cluster:github_release | https://github.com/amitpatole/verel/releases/tag/v0.35.0 | v0.35.0 — MCP recall/remember over a remote authenticated brain

12. 安装坑 · 来源证据：Add a Rust toolchain (cargo test + clippy) to the CI graders

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add a Rust toolchain (cargo test + clippy) to the CI graders
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/amitpatole/verel/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

13. 安装坑 · 来源证据：Broaden grader-parser test coverage with more real tool-output samples

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Broaden grader-parser test coverage with more real tool-output samples
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/amitpatole/verel/issues/3 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

14. 安装坑 · 来源证据：verel doctor: report installed extras and key presence

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：verel doctor: report installed extras and key presence
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/amitpatole/verel/issues/2 | 来源类型 github_issue 暴露的待验证使用条件。

15. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/amitpatole/verel | host_targets=mcp_host, claude, chatgpt

16. 配置坑 · 失败模式：configuration: v0.36.0 — TLS for routable brain/lease/registry binds

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.36.0 — TLS for routable brain/lease/registry binds
• 对用户的影响：Upgrade or migration may change expected behavior: v0.36.0 — TLS for routable brain/lease/registry binds
• 证据：failure_mode_cluster:github_release | https://github.com/amitpatole/verel/releases/tag/v0.36.0 | v0.36.0 — TLS for routable brain/lease/registry binds

17. 能力坑 · 来源证据：Docs: add a 'gate a monorepo with per-package stages' recipe

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：Docs: add a 'gate a monorepo with per-package stages' recipe
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/amitpatole/verel/issues/4 | 来源类型 github_issue 暴露的待验证使用条件。

18. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/amitpatole/verel | README/documentation is current enough for a first validation pass.

19. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/amitpatole/verel | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/amitpatole/verel | no_demo; severity=medium

21. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/amitpatole/verel | no_demo; severity=medium

22. 能力坑 · 失败模式：conceptual: Broaden grader-parser test coverage with more real tool-output samples

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: Broaden grader-parser test coverage with more real tool-output samples
• 对用户的影响：Developers may hit a documented source-backed failure mode: Broaden grader-parser test coverage with more real tool-output samples
• 证据：failure_mode_cluster:github_issue | https://github.com/amitpatole/verel/issues/3 | Broaden grader-parser test coverage with more real tool-output samples

23. 能力坑 · 失败模式：conceptual: Docs: add a 'gate a monorepo with per-package stages' recipe

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: Docs: add a 'gate a monorepo with per-package stages' recipe
• 对用户的影响：Developers may hit a documented source-backed failure mode: Docs: add a 'gate a monorepo with per-package stages' recipe
• 证据：failure_mode_cluster:github_issue | https://github.com/amitpatole/verel/issues/4 | Docs: add a 'gate a monorepo with per-package stages' recipe

24. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/amitpatole/verel | issue_or_pr_quality=unknown

25. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/amitpatole/verel | release_recency=unknown