opc/soft_quay

Fork 0

Files

T

ilaandClaude Fable 5 36d43cdf16

Harness governance / validate (push) Has been cancelled

Details

Phase 0 build gate / verify (push) Has been cancelled

Details

Require pausing on requirements conflicts; ignore local run scripts

Add a governance rule to AGENTS.md: when implementation reveals that
requirements cannot be satisfied as written (e.g. a capability the
frozen protocol cannot express), the agent must stop, record both
document sources and the technical reason in the task's execution log,
and request adjudication instead of silently narrowing scope or
altering a frozen protocol. After adjudication, every affected document
must be updated before work resumes or a new task is split off -
updating only the architecture/task docs while leaving
docs/02-requirements.md stale invalidates the acceptance criteria, which
is the drift observed in the Phase 5 trial conflict.

Also gitignore the local run-modern.bat / run-win7.bat dev scripts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-20 11:10:17 +08:00

5.0 KiB

Raw Permalink Blame History

AGENTS.md

AI coding agent 的仓库级入口。进入本仓库后,先读本文,再进入 docs/00-ai-start-here.md。

项目定位

本仓库是 SoftBox 软件盒子 主程序:使用 Go + Gio 开发的 Windows 软件盒子,覆盖软件发现、下载、安装、更新、启动和授权,兼容部分 Windows 7 用户。

采用「单仓库、单主分支、双构建」方案:

core/:共享业务核心(清单、下载、安装、更新、授权、存储),保持 Go 1.20 语法兼容,禁止 import Gio。
app-modern/:现代版(Win10/Win11 x64),当前受支持 Go + 当前 Gio。
app-win7/:Win7 遗留版(Win7 SP1),锁定 Go 1.20 + Gio v0.6.0。

本仓库不包含子软件(app-*)业务源码,也不包含服务端私钥。

必读顺序

每次开始工作前:

本文件。
docs/agent-context.json:上下文路由清单。
清单 bootstrap.always_read 中的文件(docs/00-ai-start-here.md、docs/05-coding-rules.md、docs/current-state.md)。
本轮任务文件(docs/tasks/T-<编号>.md)。
按任务类型读取清单 routes 中的文档;重复路径只读一次。

首次接入或清单校验失败时,按 docs/00-ai-start-here.md 的完整顺序读取 01→06。

硬性架构边界(违反即返工)

core/ 的 domain 与 application 不得 import Gio、SQLite 或 Windows API;依赖只进不出:app-modern/app-win7 → core,不得反向。
core/ 只使用 Go 1.20 可编译的语法和依赖;app-win7 不得引入要求 Go 1.21+ 的依赖。
Gio 只出现在 ui/gio/;Windows 能力只出现在 platform/windows/,并提供非 Windows stub 保证核心可无头测试。
Gio Layout 中不得读磁盘、访问网络、计算哈希;后台任务只发布事件,不直接改控件。
下载内容未经 SHA-256 与签名验证不得执行;解压必须防路径穿越;更新必须走 staging → current → backup 可回滚流程。
程序更新不得覆盖 data/ 和 licenses/。

完整规则见 docs/05-coding-rules.md,协议细节见 docs/api.md。

工作规则

一次只领取一个任务(docs/tasks/ 中 status: TODO 且依赖全 DONE、编号最靠前的),按 docs/tasks/README.md 约定流转状态。
执行记录写进该任务文件的 ## 执行记录;项目现实变化(启动/验证路径、目录、blocker)覆盖更新 docs/current-state.md。
需求变化先改文档再改代码;不在代码里发明文档没有的接口、字段和状态。
发现需求冲突必须暂停:实现中若发现需求之间、或需求与已冻结协议/架构之间无法同时满足(例如需求要求某能力,而协议结构上无法表达),立即停止该方向的实现,把冲突写进当前任务文件的 ## 执行记录(冲突双方的文档出处 + 技术原因),并向用户请求裁定。不得自行取舍、不得静默缩范围、不得为绕开冲突而修改已冻结协议。
裁定后文档先行:拿到裁定后,先把结论同步到所有受影响文档(需求、验收标准、架构、协议、路线图、任务边界),再继续实现或拆出新任务。只更新架构/任务文档而不回头修订 docs/02-requirements.md 会造成验收标准失效——这是已发生过的漂移(见 docs/review/phase5-review.md 的试用冲突)。
密钥、许可证私钥、真实注册码、真实下载 URL 一律不入库;示例只用占位符。
提交信息使用英文祈使句,任务相关提交带上 T-<编号>。

Agent 执行模式

后续任务默认且持续使用单 Agent 串行执行;当前 Agent 独立完成任务落文档、实现、审查、自测、状态更新和 Git 提交。
不启动子 Agent,不把测试设计、安全审查或代码审查委派给其他 Agent;需要复核时由当前 Agent 分阶段自行检查。
项目同一时间只保留一个活跃任务。T-301 → T-302 → T-303 这类依赖链严格按顺序完成和提交,不得提前并发实现后置任务。
write_paths 继续作为单任务修改边界,用于限制任务范围和提交内容,不再用于安排并行写入。
T-301 的多 Agent 执行记录保留为历史事实,不代表后续默认方式。
只有用户以后再次明确要求多 Agent,才允许先修改并提交本节及相关任务文档,再启动子 Agent;对话中的临时建议不能覆盖本规则。

验证

# core(必须可在无头 Linux/CI 运行)
cd core && go vet ./... && go test -count=1 ./...

# 现代版构建(交叉编译)
cd app-modern && GOOS=windows GOARCH=amd64 go build ./cmd/softbox

# Win7 版构建(强制 Go 1.20 工具链)
cd app-win7 && GOTOOLCHAIN=go1.20.14 GOOS=windows GOARCH=amd64 go build ./cmd/softbox

统一入口为根目录 ./init.sh / ./init.ps1;骨架未建成前(T-001 之前)脚本会提示命令未替换,属预期行为。

修改文档链接或文件名后,用 rg 搜索旧名称确认引用一致;涉及上下文清单或任务协议时运行:

python3 scripts/validate_agent_context.py
python3 scripts/validate_harness_governance.py

5.0 KiB Raw Permalink Blame History