# prfrail

**Repository Path**: larsonzh/prfrail

## Basic Information

- **Project Name**: prfrail
- **Description**: ProofRail 为 AI 无人值守编程铺设可证明的轨道——代码变更、门禁、证据、回滚，全程可审计。/ Provable rails for unattended AI engineering — every code change, gate, evidence and rollback is auditable.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: proofrail, unattended-ai, AI-Agents, audit-trail, Go语言

## README

# ProofRail（证轨）

> *Provable rails for unattended AI engineering* —— 为 AI 无人值守编程铺设可证明的轨道。

[简体中文](#简体中文) · [English](#english)

---

## 简体中文

ProofRail 让 AI 在无人值守下安全地改代码、跑验证、出证据：每一步都可验证、可回滚、可审计，
人的审批始终保留在关键节点。

- 首错即停 + 哈希绑定产物 + 原子提交回滚的“可证明写入”模型
- 相同失败指纹预算与有效修复证据判定的“防 AI 无限循环”机制
- 编辑边界矩阵与停机门禁的“AI 权限最小化”模型
- 隔离候选事务（candidate 不污染正式定义）的自愈安全模型

### 状态

**S1 实施中（2026-09-11）**：核心切片已推进至 T027 前置能力，完成证据、快照、进程/租约守卫、托管变更集与事务应用、产品生命周期，以及无 IDE CLI 基线（`init/validate/config explain/preview/approvals/interactions/cost report/secret/ai check/run/report`）。
当前仍不是正式发行包：`run` 只支持 noop-only 任务链；遇到 `code/build/verify` 步骤会 fail-close 并返回非零退出码。
`preview` 已支持离线只读静态预览（no-AI），不会执行命令、网络探测、模型调用或凭据读取。
`export` 已具备库级实现（`internal/snapshot/export.go` 与 `internal/evidence/delivery.go`），CLI 入口仍在后续切片。
`approvals` 已提供授权账本查看与撤销（`list`/`revoke`），撤销按 `stopDisposition` 接线受控停机并持久化待审批队列（重启可见）；离线、零模型调用。
`effects`/`diagnostics` 已具备库级副作用分类与恢复诊断（`internal/gates/effects.go`、`internal/evidence/diagnostics.go`）：S1 拒绝外部写，未知副作用只对账不重投，诊断只读脱敏；CLI 入口仍在后续切片。
`interactions` 已提供追加式交互账本的待办重建、结构化答复和无 ANSI 聚焦终端界面；Engine 仅在 request/response、当前绑定与等待态一致且状态事件持久化后归还控制权。真实 Agent session 续跑仍待 T027，完整统一 TUI 仍属后续切片。
`ai check` 已提供显式单请求的 `agent-runner-cli` live availability probe；它不自动执行、不跨 profile/模型/通道回退，也不证明 AgentRunner enforcement 或 AT-23。
项目建议书与历史设计来源见 [docs/RFC-proofrail-unattended-ai-engineering-product.md](docs/RFC-proofrail-unattended-ai-engineering-product.md)；分域权威见 [docs/DOCUMENTATION_PLAN.md](docs/DOCUMENTATION_PLAN.md)。

从 [docs/DOCUMENTATION_PLAN.md](docs/DOCUMENTATION_PLAN.md) 阅读文档导航与低成本模型流程；
执行顺序见 [docs/DEV_PLAN.md](docs/DEV_PLAN.md)，就绪缺口见 [docs/ADR_REGISTER.md](docs/ADR_REGISTER.md)。
独立产品端到端叙事见 [docs/BUSINESS_WORKFLOWS.md](docs/BUSINESS_WORKFLOWS.md)；尚未冻结的安装发行方案见 [docs/INSTALLATION_PLAN.md](docs/INSTALLATION_PLAN.md)。

产品完整性评审已补充无副作用预览、已接受结果导出、授权撤销、外部副作用边界、成本预留结算和备份/停用流程；见 [docs/PRODUCT_REQUIREMENTS.md](docs/PRODUCT_REQUIREMENTS.md) §8。各项实现状态以 [docs/DEV_PLAN.md](docs/DEV_PLAN.md) 为准；文件回滚不保证撤销外部操作。

### 快速开始（当前 CLI 基线）

当前界面是 Windows Terminal、PowerShell 或 VS Code 集成终端中的逐行 CLI，不是图形窗口或完整 TUI。发布候选的软硬件要求、下载核验和五步上手见 [Windows 便携 ZIP 安装指南](docs/INSTALLATION.md)。核心离线 CLI 不要求 VS Code。目标正式 AI 执行使用 AgentRunner/CLI Agent；另规划基于 SessionBridge visible 的受监督黑箱候选，可更快复用现有可见 Agent，但只保证归还后的产物检查，不保证工具、网络、费用或外部副作用。两条产品闭环当前均未交付。

```text
prfrail init --workspace .
prfrail validate --chain ./proofrail.chain.json
prfrail config explain --chain ./proofrail.chain.json
prfrail preview --chain ./proofrail.chain.json
# 仅在明确授权一次真实模型请求后执行：
prfrail ai check --chain ./proofrail.chain.json --channel agent-runner-cli --copilot C:/path/to/copilot.exe --workspace . --max-requests 1 --out ./tmp/ai-availability.json --json
prfrail ai verify --chain ./proofrail.chain.json --record ./tmp/ai-availability.json --channel agent-runner-cli --max-age 10m --max-requests 1 --json
prfrail approvals list --ledger ./authorization-ledger.jsonl
prfrail interactions list --ledger ./operator-interactions.jsonl
prfrail interactions tui --ledger ./operator-interactions.jsonl --actor-id operator-one
prfrail run --chain ./proofrail.chain.json --run-id run-demo
prfrail report --run-dir ./tmp/prfrail-runs/run-demo
```

说明：`run` 目前仅执行 noop-only 任务链；`interactions tui` 是 T025 的聚焦终端收件箱，不是完整统一 TUI，`serve`/完整 TUI 仍在后续切片。`ai verify` 可重复指定 `--prior-record <path>`，离线拒绝同一 probe ID 的历史分叉；相同记录重放保持幂等。后续黑箱模式须先展示降级保证和责任边界。SessionBridge visible 投递不等于完成，正式流程也不依赖 `@sbr-review`。

### 构建（需 Go 工具链）

```text
go build ./...
go vet ./...
go test ./...
```

### 路线图（S0–S3）

| 阶段 | 目标 | 关键交付 |
|---|---|---|
| S0 规格化 | 领域模型与协议定稿 | 文档包、JSON Schema、威胁模型、ADR |
| S1 核心任务链 | 可运行的 MVP | Chain Engine、checker、gate runner、adapter、快照/评审/恢复、TUI |
| S2 平台与语言扩展 | 走向通用 | 多 harness、Linux 支持、Web 控制台、模型策略 |
| S3 高级能力 | 产品化完整闭环 | 生成钩子场景 B、多编辑器、多语言文档 |

### 命名

| 场景 | 写法 |
|---|---|
| 正式品牌、标题、对外文档 | **ProofRail** |
| 紧凑视觉标识 | **PrfRail** |
| 仓库、CLI、包名、模块前缀 | `prfrail` |
| 中文文档 | **证轨** |

### License

MIT（见 [LICENSE](LICENSE)）。

---

## English

ProofRail enables AI to safely modify code, run validations, and produce evidence in unattended mode: every step is verifiable, reversible, and auditable, while human approval always remains at critical checkpoints.

- "Provable write" model: fail-fast on first error + hash-bound artifacts + atomic commit/rollback
- Anti-infinite-loop mechanism: identical failure-fingerprint budgets + valid-fix-evidence determination
- Least-privilege AI model: edit boundary matrix + halt gates
- Self-healing security model: isolated candidate transactions (candidate never contaminates formal definitions)

### Status

**S1 implementation in progress (2026-09-11)**: prerequisite work now reaches T027, covering evidence, snapshots, process/lease guards, managed change sets, transactional apply, product lifecycle, and a no-IDE CLI baseline (`init/validate/config explain/preview/approvals/interactions/cost report/secret/ai check/run/report`).
This is still not a production release package: `run` currently supports noop-only chains and fail-closes with a non-zero exit for executable `code/build/verify` steps.
`preview` now supports a no-AI offline read-only static report with zero command/network/model/credential execution.
`export` is now implemented at library level (`internal/snapshot/export.go` + `internal/evidence/delivery.go`); a dedicated CLI entrypoint remains in later slices.
`approvals` now provides an authorization ledger view and revocation (`list`/`revoke`) with controlled-stop wiring per `stopDisposition` and a restart-visible pending inbox; offline and model-free.
`effects`/`diagnostics` now provide library-level side-effect classification and recovery diagnosis (`internal/gates/effects.go`, `internal/evidence/diagnostics.go`): S1 denies external writes, unknown effects reconcile instead of blind retry, and diagnosis is read-only and redacted; CLI entrypoints remain in later slices.
`interactions` now rebuilds pending items from an append-only ledger, records structured responses, and provides a focused ANSI-free terminal UI. The Engine returns control only after request/response, current binding, waiting state, and durable state events agree. Real Agent-session continuation remains T027 work, and the complete unified TUI remains a later slice.
`ai check` now provides an explicit single-request `agent-runner-cli` live availability probe. It never runs automatically, falls back across profiles/models/channels, or proves AgentRunner enforcement or AT-23.
Project proposal and historical design source: [docs/RFC-proofrail-unattended-ai-engineering-product.md](docs/RFC-proofrail-unattended-ai-engineering-product.md). Domain authorities: [docs/DOCUMENTATION_PLAN_EN.md](docs/DOCUMENTATION_PLAN_EN.md).

Start with [docs/DOCUMENTATION_PLAN_EN.md](docs/DOCUMENTATION_PLAN_EN.md) for navigation and the low-cost model workflow;
see [docs/DEV_PLAN_EN.md](docs/DEV_PLAN_EN.md) for tasks and [docs/ADR_REGISTER_EN.md](docs/ADR_REGISTER_EN.md) for readiness gaps.
See [docs/BUSINESS_WORKFLOWS_EN.md](docs/BUSINESS_WORKFLOWS_EN.md) for the independent end-to-end product narrative and [docs/INSTALLATION_PLAN_EN.md](docs/INSTALLATION_PLAN_EN.md) for unresolved installation and distribution decisions.

Product review adds side-effect-free preview, accepted-result export, revocation, external-effect boundaries, cost reservation/settlement and backup/retirement flows. See [docs/PRODUCT_REQUIREMENTS_EN.md](docs/PRODUCT_REQUIREMENTS_EN.md) section 8 and [docs/DEV_PLAN_EN.md](docs/DEV_PLAN_EN.md) for each capability's implementation status. File rollback cannot guarantee undoing external effects.

### Quick Start (current CLI baseline)

The current interface is a line-oriented CLI in Windows Terminal, PowerShell, or the VS Code integrated terminal, not a graphical window or complete TUI. See the [Windows portable ZIP installation guide](docs/INSTALLATION_EN.md) for candidate hardware/software requirements, download verification, and the five-step quick start. Core offline mode needs no VS Code. Target formal AI execution uses AgentRunner/CLI Agent; a separate SessionBridge-visible supervised black-box candidate mode is planned for faster reuse of an existing visible Agent, but warrants post-return artifacts only, not tools, network, cost, or external effects. Neither product loop is delivered yet.

```text
prfrail init --workspace .
prfrail validate --chain ./proofrail.chain.json
prfrail config explain --chain ./proofrail.chain.json
prfrail preview --chain ./proofrail.chain.json
# Run only after explicit authorization for one live model request:
prfrail ai check --chain ./proofrail.chain.json --channel agent-runner-cli --copilot C:/path/to/copilot.exe --workspace . --max-requests 1 --out ./tmp/ai-availability.json --json
prfrail ai verify --chain ./proofrail.chain.json --record ./tmp/ai-availability.json --channel agent-runner-cli --max-age 10m --max-requests 1 --json
prfrail approvals list --ledger ./authorization-ledger.jsonl
prfrail interactions list --ledger ./operator-interactions.jsonl
prfrail interactions tui --ledger ./operator-interactions.jsonl --actor-id operator-one
prfrail run --chain ./proofrail.chain.json --run-id run-demo
prfrail report --run-dir ./tmp/prfrail-runs/run-demo
```

Notes: `run` currently executes noop-only chains. `interactions tui` is T025's focused terminal inbox, not the complete unified TUI; `serve` and the complete TUI remain later slices. `ai verify` accepts repeatable `--prior-record <path>` inputs, rejects historical forks for one probe ID offline, and treats identical record replay as idempotent. The later black-box mode must show its reduced assurance and responsibility boundary before selection. SessionBridge visible delivery is not completion, and the formal path does not depend on `@sbr-review`.

### Build (requires Go toolchain)

```text
go build ./...
go vet ./...
go test ./...
```

### Roadmap (S0–S3)

| Phase | Goal | Key deliverables |
|---|---|---|
| S0 Spec | Finalize domain model and protocols | Docs package, JSON Schema, threat model, ADR |
| S1 Core chain | Runnable MVP | Chain Engine, checker, gate runner, adapter, snapshot/review/recover, TUI |
| S2 Platform & language extension | Go general | Multiple harnesses, Linux support, web console, model policies |
| S3 Advanced capabilities | Full productized loop | Generated hook scenario B, multiple editors, multilingual docs |

### Naming

| Context | Spelling |
|---|---|
| Official brand, titles, external docs | **ProofRail** |
| Compact visual identity | **PrfRail** |
| Repo, CLI, package, module prefix | `prfrail` |
| Chinese docs | **证轨** |

### License

MIT (see [LICENSE](LICENSE)).