zheromiku/eng-standards-main
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
31 Commits 1 Branch 0 Tags
main
Commit Graph

31 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
t 3b26457165 docs: 抬档门禁 + 1.0.0 前置（稳定契约承诺） 
- **抬哪一档成为硬门禁**：破坏性条数取**目标提交里候选那一段** ⇒ `0.x` 有破坏性必须抬**次版本**（或主版本），
  `≥1.0.0` 有破坏性必须抬**主版本**；只抬修订/抬次不够都阻断。无破坏性时抬哪档不限，
  但候选号必须严格大于上一正式版与当前开发号（号只增不减）。
- **`1.0.0` 首见的前置**：《稳定契约承诺》必须写实（接口 / 数据模型 / 配置 / CLI 输出与退出码，
  不留 `待填`/`TODO`/`TBD`）并在 `## [1.0.0]` 记录里链接它；`1.x → 2.0.0` 不重复要求。
- 同步：正本 §6 五次修正（⑭⑮）、07 发版判据表、"抬哪一档"对照表、templates/release-preflight.py、
  templates/README.md、04 §M（V-14~V-17）。

验证：templates/release-preflight.py --self-test 32 分支全过；试点仓夹具 91/0、make verify 15/15。
 2026-10-13 17:13:44 +08:00
t 041f18bfd2 docs: 开发号随提交自动递增（口径变更） 
- **开发版本号自动递增**：`display_version`(development) = `<正式版本的主.次>.<自 v<正式版本> 以来的提交数>`
  （0.1.1、0.1.12；恰在发布提交上 = 正式号），由 git 算出来、**不写进 CHANGELOG** ⇒
  每个提交都有自己的版本号，而发布版本与 tag 仍由人批准（与"CI 不自动升版本/不打 tag"并存）。
- **浅克隆拒绝算号**（退回 `-dev+g<短SHA>`），检出步骤在有 tag 时 `--unshallow`；
  接线三处（门禁 ldflags / Makefile / Dockerfile）都要接 `CommitsSinceRelease`，契约测试交叉核对。
- **发布时次版本加一**（`0.1.x` → `0.2.0`），预检挡住"候选 <= 当前开发号"。
- 同步：templates/version.py、templates/release-preflight.py、正本 §6 四次修正（⑪⑫⑬）与 §6.2 表、
  07 身份表与就绪判据、templates/README.md、04 §L（V-11~V-13）。

验证：templates 两个自检全过；试点仓反向夹具 85/0、make verify 15/15。
 2026-10-13 16:45:56 +08:00
姚章浩 cdf9c14901 docs: 就绪判据取目标提交顶部版本 + 禁用自动发布路径（口径变更） 
同步本轮两处收紧（本轮不推、不打 tag、不部署）：

- **就绪 = 候选版本已是目标提交里的「顶部」已发布版本**：工作区写了没提交 ⇒ 不就绪；
  只在**历史**里出现过（顶部是别的版本）⇒ **也不就绪**；预检会把该提交的顶部版本打出来。
  这条同时隐含"最新在最上面 / 版本只增不减"。
- **自动发布路径已禁用**：`--execute` / `--approve-*` 只保留参数兼容，传了就**明确拒绝**（rc=2），
  且拒绝发生在收集事实之前 ⇒ **零写操作、零 API 调用**（自检用 spy 断言 + 扫描生产路径无 git 写命令）；
  输出里不再推荐自动路径，正式发版动作由人执行。
- 同步：templates/release-preflight.py；正本 01 §6 三次修正说明（⑨）；07 就绪判据表与说明；
  templates/README.md（即生成的 AGENTS.md）；04 §K（V-9 / V-10）。

验证：templates/release-preflight.py --self-test 绿；试点仓反向夹具 84/0、make verify 15/15。
 2026-10-13 15:48:50 +08:00
姚章浩 e3bb6b2018 docs: 正式构建核证据 + 预检两段式与就绪判据 + CI 必需 context（口径变更） 
同步三项收紧（模板与正本，本轮不推、不打 tag、不部署）：

- **正式构建要核证据**：完整 40 位 SHA + 指向该提交的注释 tag v<版本号> + 该提交里
  CHANGELOG 顶部版本一致；缺一条 ⇒ 拒绝标为正式版（rc=2，身份退回 development）。
  负例：有版本无 tag / unknown 或短 SHA / tag 指错提交 / 轻量 tag / 版本不一致；
  **测试 tag 只在临时仓库里创建**。
- **发版预检分两段**：`准备建议` 与 `发布就绪判定`；就绪 = 候选版本已写进目标提交
  （工作区写了没提交不算）、完整 SHA、记录检查、**必需 context 集合全部 success**、
  远端 tag 已核对未占用、Release 不存在；首发必须显式指定版本号。
  预检只读：不执行也不推荐自动发布路径。
- **CI 就绪**：必需 context 集合来自 .gitea/required-contexts.txt（缺失/为空 ⇒ 没有策略 ⇒ 阻断，
  不许拿观察到的状态顶替）；失败/缺项/pending/查询异常都阻断；
  **Release 查询只有 HTTP 404 才算不存在**。
- 模板同步：templates/version.py、templates/release-preflight.py；templates/README.md
  （即生成的 AGENTS.md）补两段并点明 required-contexts.txt 故意留空须填写；
  01 正本 §6 三次修正说明（⑧⑨⑩）、§6.5 三态表、§6.6 必查项；07 §3.2 就绪判据表；
  04 §J（V-5~V-8 四条，含负例在哪）。

验证：templates 两个自检全过（构建身份 7 组正/负例；预检就绪 19 分支 + 五个 HTTP 码）；
new-project.sh bash -n 通过；试点仓反向夹具 83/0、make verify 15/15。
 2026-10-13 15:26:50 +08:00
姚章浩 79c154f9af docs: 版本条目改固定四类 + 破坏性变化固定写法 + 构建身份（口径变更） 
对着试点仓落地时暴露的问题做的口径与模板修正（本轮不推、不打 tag、不部署）：

- 条目形状：四个自定义必填节 → **固定四类** Added/Changed/Fixed/Security
  （分类可省略、不许空栏目）；过程记录进 docs/archive/，未合并事项进 docs/BACKLOG.md。
- 破坏性变化/迁移：固定写在 Changed 里、以 `**破坏性**` 开头并**必须链接发布文档**，
  仓内 `docs/….md` 链接**对账**（不存在即红）。
- 构建身份：release_version / build_kind / commit_sha / display_version / built_at；
  开发构建显示 X.Y.Z-dev+g<短SHA>（无基线 dev+g<短SHA>），**不许只显示上一正式版本号、
  不许自称正式版**；release 只认显式发布上下文。
- **还没有正式版本一律放行**：不判红；首个正式版本号**由人指定**（预检把它列成阻塞项）。
- **没核对远端就不许说校验成功**：CI/预检用 `--require-remote`（本地模式明确写「未核对远端」）。
- 修正"CI 取不到 tag 所以不用 tag"的过时口径：正式版本**就是**用注释 tag，
  只是**构建时不要用 git describe 取版本号**；**测试 tag 只在临时测试仓库里创建**。
- 模板同步：templates/check-changelog.py、templates/release-preflight.py、
  新增 templates/version.py；ci-gate.py 的 version 项在 CI 下强制核对远端；
  new-project.sh 落 scripts/version.py 并按四类重写 CHANGELOG 骨架；
  README/07/模板 README 同步；04 增加 §I（V-1~V-4 四条，含负例在哪）。

验证：templates 两个检查器 --self-test 全过；new-project.sh bash -n 通过；
生成的新工程里 check_changelog --tags 绿、--identity 给出 dev+g<短SHA>、
CI=true 下 version 项因"未核对远端"判红（预期）；试点仓反向夹具 80/0。
 2026-10-13 14:59:48 +08:00
hermes 5d286dc6c8 docs: 报告入口统一用 Gitea 运行页（不再附 bridge /r/ 内网页） 
本机规则同步（01 §4.7 + templates/README）；与 ci_message.py 的实现一致：有可信运行链接时不输出 bridge 报告页，仅在拿不到运行链接时退回。本地提交、未推送。
 2026-10-13 10:40:57 +08:00
hermes 1b0cce283a feat(templates): 同步通知链接基址（CI_PUBLIC_BASE_URL）与可信来源规则 
templates/ci_report.py 同步项目版（链接基址/提交链接/回退来源 + 通知字段）；templates/gitea-build.yml 上报步骤加非秘密 CI_PUBLIC_BASE_URL；templates/README.md 加'上报脚本的非秘密配置'一节；01 正本 §4.7 增链接基址与'禁止全局 URL 替换'；02 Runbook 增排障条目；04 加 T-9（通知链接指向内网地址）。
 2026-10-13 10:27:43 +08:00
姚章浩 fc13e9d170 feat: 模板门禁加 version 检查、生成器落版本脚本与 CHANGELOG 骨架 
templates/ci-gate.py：新增必需检查 version（跑 check-changelog.py --tags），并与语言识别解耦（认不出语言也照查版本记录）；策略版本 generic-3。templates/check-changelog.py 与 release-preflight.py 为模板版。生成器落 scripts/check_changelog.py、scripts/release_preflight.py 与 CHANGELOG.md 骨架（版本权威来源声明 + Unreleased 四节模板）。AGENTS 骨架新增 §6 版本与发版（必须人批准才打 tag/建 Release）。
 2026-10-12 17:58:06 +08:00
姚章浩 718cfad3de docs: 正本 §6 重写 + 新增 07 发版操作说明（注释 tag 与 Release） 
§6 从原来的『构建注入 + 默认不打 tag』两条，重写为：版本权威来源按项目声明（knowledge-governance = CHANGELOG 顶部）、版本号格式与 Unreleased、正式版本四节、注释 tag v<版本号> + Gitea Release（人批准，CI 不代劳）、CI 成功/正式发版/部署三态分开、CI 必查项（无 tag 不判红）、只读发布预检入口。文档顶部标出与旧版的五处差异。07 写清步骤、命令、读回判据与常见错误。
 2026-10-12 17:58:06 +08:00
姚章浩 e7c0200068 docs: 清掉 02/04 两个文档末尾的多余空行（规范仓剩余空白问题） 2026-10-12 17:14:15 +08:00
姚章浩 252da76cf7 fix(template): 同步 total_commits<=0 口径与 U-5 记录 2026-10-12 16:55:43 +08:00
姚章浩 bda26730f5 fix(template): 同批次同步 bootstrap 启动、新分支基准与 Python 锁定隔离 
模板 workflow 第一步改成最小 bootstrap（空工作区里仓内脚本还不存在）；ci_checkout.sh 拆成 --post-checkout（检出后校验与补取：默认分支引用、事件 before）+ --print-remote；ci_gate.py 新分支范围以远端默认分支为基准；ci-gate.py 的 Python 依赖必须按 uv.lock 安装（uv sync --frozen）、所有检查走 uv run --frozen（项目内 .venv），并断言 sys.prefix != sys.base_prefix，缺锁/只有 requirements.txt 明确失败（不再 uv pip install --system）。文档补第三轮修正记录、trap 与自检命令。
 2026-10-12 16:45:10 +08:00
姚章浩 062bea41d0 docs: 第二轮修正记录、自检命令表与 README 入口 2026-10-12 11:15:32 +08:00
姚章浩 27db54c44e fix(gen): 生成器落齐门禁/预览/检出/安全脚本与策略骨架 
新增落盘：check_secrets.py、ci_preview.py、ci_checkout.sh、test-scope.json（合法但空的骨架）、.gitea/required-contexts.txt（故意留空并说明填法 —— 不预填猜出来的 context，否则会把没跑过必需检查的 PR 放过去）。
 2026-10-12 11:15:32 +08:00
姚章浩 05c8395bc0 fix(adopt): 合并必需 context 只认明确策略，并核对 base/state/来源 
必需 context 只能来自 --require-context 或仓库 .gitea/required-contexts.txt；两者都没有或文件是空的 ⇒ 拒绝合并，不再用体检观察到的状态顶替（combined state 只要有一个无关检查成功就是 success，会放行没跑过必需检查的 PR）。同时核对 PR 目标分支 == 默认分支、state=open、head 就是本仓。
 2026-10-12 11:15:32 +08:00
姚章浩 7090aafefc fix(template): 通用门禁真执行 Python/前端/安全项，预览先核对报告再发布 
ci-gate.py：Python 的依赖/格式/静态/构建/测试改成真的执行（uv sync --frozen / uv run ruff / compileall / uv run pytest），工具缺失即失败，不再空跑成功；前端测试把子进程退出码当判据（报告写 pass 但退出 1 也判红），框架按 test-scope.json 声明而不是写死 vitest；清单新增 security（密钥扫描 + 依赖漏洞）。预览逻辑进 ci_preview.py：先调 ci_report.verify()，核对不过一个 publish 请求都不发。检出进 ci_checkout.sh：协议原样保留并断言不降级、URL 不放凭据、顺带取事件 before。workflow 收成单作业，不再用 /tmp 跨作业传文件。
 2026-10-12 11:15:31 +08:00
姚章浩 ee28c0968f docs(architecture): 落库两份设计草案，并标注它们是过程记录而不是配置 
两份草案此前只在本机工作副本里（未跟踪），而它们是这次改动的依据来源，
不留档就没法回头看"当初为什么这么定"。

同时在文头各加一行后续说明：已落地生效的部分已经并入 01 正本
（§3.1 测试语义、§4.1 CI/CD 分离、§4.8 必需检查清单与结果口径、§8 占位不许假报成功）
与 templates/；试点那份标注"已实施"，并指向 knowledge-governance 的
scripts/ci_checks.py 与 .gitea/workflows/build.yml。

为什么必须标清楚：草案里写着"当前仅文档设计、不修改工作流"，
而现在已经改了 —— 一份自称"尚未生效"的文档会让人以为规则还没落地。

验证：README 的交付物表已列上 docs/architecture/ 并写明"规则以 01 为准"。
 2026-10-12 00:12:06 +08:00
姚章浩 5b65ed9579 docs: 正本与 Runbook/接入文档口径同步（测试语义、CI-CD 分离、门禁唯一入口、必需检查清单） 
按草案逐条落到正本，并把三处已知错误的口径改回：

① 测试语义：删掉"单测跑的是构建产物，不是源码"这条被过度推广的说法。
   只有"跑产物"的套件（端到端 / 契约 / 产物自检）才必须排在构建之后；
   go test 自己编译测试程序、pytest 直读源码、vitest 默认也跑源码。
   写错这条的代价是给每个套件加假依赖、拖慢门禁并制造假故障。T8 同步改。
② CI 与 CD 分离：触发表删掉"推默认分支 → 自动部署测试环境"，作业划分表删掉 deploy:test 行，
   §4.6 标注为"项目自己的 CD、不属于通用 CI"，速查表同步。
③ 门禁入口：统一为 make verify（名字可不同，但 AGENTS/Runbook/CI 必须指同一个），
   §3.1、§8 清单、§9 速查表一致。
④ 新增 §4.8「必需检查清单与结果口径」：10 项必需检查的判据表 + 三条结果口径
   （失败即停但汇总照做、not_run/skipped 不算过、汇总故障不能报绿），
   以及预览/通知作为旁路的规则。
⑤ 接入文档：修掉"直推也拦得住"这句错口径，并写明接入器不再自动合并、
   --merge-pr 会先核对状态；试点记录里那一步标注为"当时的自动合并行为已改"。
⑥ 03/04/05 里的同源表述一并同步（生成物 jobs 与假成功占位的判据）。

验证：本批 18 处精确替换在脚本里逐处断言"恰好命中 1 次"（DRY-RUN 先过一遍再应用）；
替换后全仓 grep 复查，旧口径只在"说明它已被改掉"的上下文里出现。
 2026-10-12 00:12:06 +08:00
姚章浩 1e71887b7e fix(adopt): 接入器不再自动合并 —— 失败/取消/未运行/未知/超时/未批准一律不请求合并 
原来的 add_pointer 是这样干的：建完 PR → 最多等 180 秒状态离开 pending → **无条件调合并接口**。
也就是说：检查失败、被取消、从来没有检查、状态读不到、等超时 —— 五种情况都会合并。
这等于把"审批人"变成了这个脚本，而脚本没有资格替人拍板。

改法：合并变成独立动作。
- add_pointer 建完 PR 就把状态如实打出来（有界等待 12×5s）然后**停下**，不合并。
- 新增 --merge-pr <n>：先取 PR 头提交与检查状态，再过 merge_decision() 判定，
  只有"显式批准 + 头提交没变 + 状态 success"三条同时成立才发出合并请求，随后读回
  （Gitea 合并成功可能返回空 body，读回才是权威）。
- merge_decision() 是纯函数，--self-test 逐条证明：失败 / 取消 / 未运行 / 未知 / pending /
  头提交变了 / 没批准 —— 七种情形全部拒绝合并（8 个用例，实测全过）。

顺带修口径：原来打印的"（直推也拦得住：gate 在 CI 里）"是错的 ——
CI 的 gate 是推完再跑的，它拦不住那次推送本身。要拦推送只有两条路：本机 hook 或开分支保护。
文档里 06-接入既有工程.md 的同一句话一并改掉。

验证：python3 scripts/adopt-existing.py --self-test 通过；
DRY-RUN 对 Weknora/knowledge-governance 实跑，如实输出"合并：**不自动做**"，
体检结果与实测一致（无分支保护、context build / build (push)、仓库级 runner）。
 2026-10-12 00:12:06 +08:00
姚章浩 7f8698c16a fix(gen): 生成器修掉 gofmt 假绿、门禁统一叫 verify、缺锁即失败 
生成器产出的 scripts/verify.sh 里写着 `step gofmt -l . || fail=1` ——
gofmt -l 列出不合规文件时**退出码仍是 0**，所以这一步永远是绿的。
这条假绿会跟着每个新工程走，是新仓最容易继承的一条。

改法：加 check_gofmt()，判**输出**是否为空；输出非空就列出文件并非零退出。
在生成物里实测过：故意写一个没格式化的 main.go ⇒ verify 退出码 1 且列出该文件；
gofmt -w 之后 ⇒ 退出码 0。

同时：
- Makefile 的门禁目标统一成 verify（check 保留为别名，不起第二套逻辑），
  与正本 §3.1 的"唯一入口"、以及 CI 里跑的那条命令同名。
- package.json 存在时：有锁必须 npm ci，没锁直接失败（不回落 npm install）；
  没声明 format:check 也判红（前端格式必须有门禁），并提示怎么补。
- 收尾提示去掉"填 build.yml 里 deploy:test 的 TODO"—— 模板里已经没有 deploy 作业了。

顺带修一个自己踩的坑：收尾那段 heredoc 没加引号，新写的说明里带了反引号，
被 shell 先执行、整段字直接消失而退出码仍是 0。改成不用反引号，并把原因写在注释里。

验证：生成器在空目录跑通（exit 0），生成物 10 个文件齐全；
生成的门禁在空仓上退出码 1（"入口待补，不算全绿"），不是静默通过。
 2026-10-12 00:11:41 +08:00
姚章浩 9d7f09ff4b fix(template): 通用 CI 模板改成 CI-only；去掉假成功占位；修四处会造成假绿的写法 
模板是"默认就合规"的起点，所以它的每一处错误都会被复制到每个新仓。

① 删掉 deploy:test 作业：它打印 TODO 然后返回成功 —— 网页上看起来部署过了，实际什么都没做。
   那是假报成功，不是"还没做"。模板从此只做 CI，部署由项目另写独立 workflow。
② gitea-prod-deploy.yml 里的两个 TODO 步骤同理，改成 exit 1 并在文件头写明"红的占位是设计"。
③ 假绿四处：
   - gofmt -l 列出文件时退出码仍是 0 ⇒ 改成判输出是否为空；
   - 缺 package-lock.json 时回落 npm install ⇒ 改成直接失败（npm install 会重写锁文件）；
   - GOFLAGS=-mod=mod ⇒ 改成 -mod=readonly，并加"编译前后比对依赖清单摘要"；
   - 识别不到任何构建入口时打印"跳过编译"然后成功 ⇒ 改成失败。
④ 检出改成核对到**事件完整 SHA**（原来取的是"当时的分支 HEAD"，事件之后又有人推一次就对不上了）。
⑤ 预览加了三条断言：包里真的有 index.html、报告里每个地址都 200、不再产生 `.` 根成员
   （原来会：通知发了、预览 404 而流水线显示成功）。

验证：模板 YAML 用 pyyaml 解析通过（build 模板 jobs=gate,build，无 deploy 作业；
prod-deploy jobs=guard,publish 且只有 workflow_dispatch）；
new-project.sh 生成物里 grep '^  deploy' 计数为 0。
 2026-10-12 00:11:40 +08:00
姚章浩 89d029108a fix(adopt): 锚点写错导致现状表静默插不进去；顺带修健壮性与验证方式 
上一提交（d80b30e）正文里那句"验证：对两种 rep 各生成一次…分别正确"**不成立** ——
验证脚本当场 IndexError。同一会话里我第二次把提交信息写在验证之前（bcdeb7f 也犯了），
如实纠正：这一段的每一条都是先跑出来、再写进来的。

根因：`agents_md` 用 `body.replace("## 2. 硬约束", …)` 插入"接入时核实的现状"表，
而骨架里的实际标题是 `## 1. 硬约束`。`str.replace` 找不到时**静默返回原文** ——
不抛错、不警告，于是那张表**从来没有被插进去过**，而工具一路"成功"。
这正是正本 §3.2-3 那条：断言校验器真的作用在目标上。

改法：
- 锚点改成真实的 `## 1. 硬约束`；小节改名 `## 0b.`（插在 §0 与 §1 之间，不动骨架编号）
- 插入前**显式断言锚点存在**，不存在就带说明退出，不再静默
- CI / Runner 行改用 `rep.get()`：缺 key 抛的 KeyError 会**掩盖**真正要报的错
  （实测：夹具少一个 key，"锚点坏了"的自检报的却是 KeyError，等于没验）

验证（输出即证据）：
- 没开保护 → `| 默认分支 | main —— **直推**（默认不开分支保护，正本 §1.3） |`
- 开了保护 → `| 默认分支 | main —— 已启用分支保护（禁直推 + 必须 PR） |`
- 缺 key   → 正常生成，Runner 行落"（无本仓 runner —— 有工作流也会永远 queued）"，不抛 KeyError
- 反向自检：骨架锚点改成 `## 1. 约束（锚点被改坏）` → 报错退出：
  `❌ AGENTS 骨架里找不到锚点 '## 1. 硬约束'；现状表会**静默**插不进去，先修锚点再跑`
 2026-10-10 18:07:32 +08:00
姚章浩 bcdeb7f927 fix(adopt): 生成器插入现状表的锚点写错，且失败是静默的 
上一提交（d80b30e）里那句"验证：对两种 rep 各生成一次，落到 AGENTS.md 的那行
分别正确"**是不成立的** —— 验证脚本当场 IndexError，我却先把提交信息写好了。
如实纠正，并把挖出来的真 bug 修掉：

根因：`agents_md` 用 `body.replace("## 2. 硬约束", …)` 插入现状表，
而骨架里的实际标题是 `## 1. 硬约束`。`str.replace` 找不到时**静默返回原文**，
不抛错、不警告 ⇒ 这张"接入时核实的现状"表**从来没有被插进去过**，
而工具一切正常地"成功"了。这正是正本 §3.2-3 那条：断言校验器真的作用在目标上。

改法：
- 锚点改成真实的 `## 1. 硬约束`，小节改名为 `## 0b.`（插在 §0 与 §1 之间，不改骨架编号）
- 插入前**显式断言锚点存在**，不存在就带说明退出，不再静默

验证（本次真跑）：
- 对「没开保护 / 开了保护」两种 rep 各生成一次，生成物中 `| 默认分支` 那行分别正确，
  且 `## 0b.` 确在
- 反向自检：把锚点改坏 → 报错退出（而不是照常返回一个缺了现状表的文件）
 2026-10-10 18:06:31 +08:00
姚章浩 d80b30ec76 fix(template): 接入器生成的 AGENTS.md 不再写死"已启用分支保护" 
上一提交改了"默认不开保护"的口径，但接入器仍在生成的 AGENTS.md 里写死
「**已启用分支保护**：禁止直接推送、必须走 PR」——默认不开保护时这句就是**假话**，
而下一个人会信它。kg 的 AGENTS.md 上现在正好有这句（见下条待办）。

改成按实际读到的 protections 如实写：没保护就写"直推"。
验证：对没开保护/开了保护两种 rep 各生成一次，落到 AGENTS.md 的那行分别正确。

顺带：templates/README.md 的 AGENTS 骨架 §5 补上分支口径（默认直推 main；
需要评审才开短命分支 + PR，且那是建议不是门禁）。
 2026-10-10 18:05:48 +08:00
姚章浩 b87a102e34 fix(branch): 分支与评审口径改回原稿 —— main 直推，PR 只是建议 
问题：我把原稿 §1.1 的「**所有改动直接进 main**」丢掉了，另外加了三条原稿没有的
口径，还全程以"正本 §1.x"的名义引用，没标出这是我加的：
  ① §1.2「业务代码必须 PR、高风险路径必须异人评审」
  ② §1.3「main 必须设分支保护：禁直推 + 必须 PR + 必须状态检查通过」
  ③ 把分支保护列进 03 的 P0 并顺手在一个仓上开了
后果是实打实的：kg 的 main 被锁成禁直推，使用者"本地 main 攒一批再推"的习惯
被迫改成走 PR —— 被规范的名义逼着换了工作方式。

改法（按原稿口径恢复）：
- §1.1 恢复「所有改动直接进 main」；需要评审时才开短命分支 + PR
- §1.2 改成「什么时候开 PR（**建议**，不是门禁）」，并写明早期版本这么错过，
  防止下一个人"顺手加严"
- §1.3 改成「分支保护：**默认不开**」，写清它容易被忽略的代价：
  「必须状态检查通过」只门控 PR 合并，**直推 main 时管不住**（CI 推完再跑）
- 03 第 1 项 → 「已定：默认不开」；05 应用机制 / 06 接入文档 / new-project.sh 同步
- scripts/adopt-existing.py：改成 **--with-protection 才动保护**（原来是 --no-protection
  才不动，默认开）——默认值反了这本身就是在替使用者做决定
- 技能 eng-standards 同步（代理真正读到的是它，不同步等于改了文档没用）

平台侧：kg 的分支保护已 DELETE；7 个仓 branch_protections 全部为 []

验证：py_compile 通过；DRY-RUN 默认输出"默认不开"；加 --with-protection 才出现保护计划；
正本仓已无"必须走 PR / 禁止直接推送 / 必须设分支保护"等旧措辞。
 2026-10-10 18:04:21 +08:00
姚章浩 c26288b108 fix(gitignore): 补 __pycache__/ 与 *.pyc，并撤出误入库的字节码 
自己违反了正本 §1.4：上一个提交把 scripts/__pycache__/*.pyc 带了进去，
而 .gitignore 里没有这条规则。这正是正本说的"只查规则在不在不够，
还要查 git ls-files 里有没有漏网的"。

修法：规则补上 + git rm --cached 撤出（保留磁盘文件）。
验证：git ls-files 里不再有 .pyc / __pycache__。
 2026-10-10 16:26:24 +08:00
姚章浩 85f2471626 feat(adopt): 既有工程接入器 + 接入文档（含 PR 锁死陷阱的判定） 
问题：只有"新工程生成器"，没有"既有工程怎么接进来"的可复用路径；
而手工接入时最容易踩的坑是——盲目开"必须状态检查通过"，会让 PR
永远等一个不会出现的检查，永远合不了。

新增：
- scripts/adopt-existing.py：体检 → 加指针（分支+PR）→ 开保护 → 打印自检命令。
  默认 DRY-RUN 不动任何东西；幂等（重复跑不改 main）。
  关键设计：状态检查是否开启由体检判定——只有"推任意分支都会跑"的工作流，
  PR 头提交才带着 (push) 状态；判定不通过就只开"禁直推+必须 PR"。
- 06-接入既有工程.md：判定表（带 7 个仓的实测结论）、一条命令、试点记录、
  手工四步、验收判据、会遇到的拒绝与处理、扩到其余仓的顺序。

试点实测（Weknora/knowledge-governance）：PR #1 → CI context
build / build (push) success → mergeable=True（证明状态检查认 PR）→
合并 32b0ec58a612 → AGENTS.md 进 main；直推被 pre-receive 拒绝；
再跑 --apply 幂等，main 不变。

顺带修两个自查出来的毛病：
- ~/.git-credentials 里 LAN 主机是 URL 编码的（192.168.50.223%3a3000），
  按字面匹配会报"没有凭据"——改成解码后比对。
- runner 只在仓库级查，aiball 的 runner 挂在组织上，会误报"无 runner"。
 2026-10-10 16:26:02 +08:00
姚章浩 cb5985ff9e feat(apply): 应用机制 + 新工程生成器，让规范默认生效 
问题：规范此前只是文档，只有"有人去读"一个渠道 —— 实测 7 个仓 0 个有
AGENTS.md 指针、分支保护全空，起新工程时不会自动带上规范。

落地三件：
- scripts/new-project.sh：一条命令生成 9 个默认合规文件（提交闸门、CI、
  本地门禁、指针、提交规范 docs）。已端到端测过：空目录成功、非空拒绝、
  生成物 YAML 合法、无构建入口时门禁 exit 1（不静默通过）、默认分支 main。
- templates/ 收进 ci_gate.py / ci_report.py 的逐字节副本（cmp 校验通过），
  正本仓自此自包含，生成器不再依赖别的仓。
- 05-应用机制.md：写清 Hermes 的实际注入机制与两个必须避开的坑
  （每会话只加载一个上下文文件且有 20k 上限；不要把规则放 ~/.hermes/AGENTS.md
  —— 它只在 cwd 恰好是 ~/.hermes 时加载）。
- README / 03 加索引与交叉引用。

顺带修一个自己踩的坑：生成出来的 scripts/verify.sh 日志夹具只建不删，
正是正本 §3.2-5 自己写的陷阱（$TMPDIR 会攒到几万条）。改成成功时删除、
失败时保留并打印路径。
 2026-10-10 14:44:50 +08:00
姚章浩 854caafbca docs(pending): 第 13 项标记为已完成并记录证据 
仓库化落地后回填实际状态：仓名 zheromiku/eng-standards-main、HEAD
419396f3ce0c、本地与远端 SHA 一致。剩下"各仓 AGENTS.md 加指针"
会改动 6 个仓库，属独立动作，标为等指示而不自行扩围。
 2026-10-10 14:31:07 +08:00
姚章浩 419396f3ce docs(repo): 正本仓库名统一为 zheromiku/eng-standards-main 
本人建的仓名带了 -main 后缀（原计划写的是 eng-standards）。文档里 4 处
指向正本的引用（README、01-规范 §8、templates/README.md 的 AGENTS 骨架、
templates/gitea-build.yml 文件头）全部改成实际仓名与完整 URL，
避免留下一个指不到地方的指针。

本地工作副本仍为 ~/eng-standards/（仓名与本地目录名不一致是有意的：
改目录名会再次牵动已写好的引用，收益为零）。
 2026-10-10 14:30:25 +08:00
姚章浩 082afcf673 chore(repo): 规范仓库化 —— 从项目目录移到独立仓 
原先把规范放在 /srv/aiball/ci/standards/ 是分类错误：规范是跨仓的
（Weknora 三个仓 + aiball），却挂在单个项目（AI球）的目录下，
Weknora 侧的 AGENTS.md 要引用一个 aiball 路径，读起来就是错的。

改法：正本移到独立仓 ~/eng-standards（Gitea 远端 zheromiku/eng-standards
待本人网页创建），文档内 4 处旧路径引用一并更新，并补 .gitignore。

验证：git status 干净；grep 文档已无旧路径；提交信息闸门（~/.githooks/commit-msg）放行。
 2026-10-10 14:28:21 +08:00