Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .cursor/rules/governance-change.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
description: 改治理面(workflow / 治理脚本 / AGENTS.md / .mdc / docs/governance)时的纪律:同源脚本不单仓改、宪法块不改、required check 与分支规则同日同步、新闸 enforce 起步(软化必带 enforce-by ≤ 30 天)、新 workflow 必登记、元规则改动独立 PR、治理 PR 先看到新闸全绿再合。Use when editing .github/**, scripts/*.py, scripts/*.sh, docs/governance/**, AGENTS.md, CONTRIBUTING.md or .cursor/rules/*.mdc.
globs: .github/**,scripts/*.py,scripts/*.sh,scripts/data/*.json,docs/governance/**,AGENTS.md,CONTRIBUTING.md,.cursor/rules/*.mdc
alwaysApply: false
---

# 改治理面的纪律(母仓 `aullik5/krow` 研发纪律第七节 / 修订协议第十二节 与 ci-workflow-governance 规则在本仓的落法)

1. **先分清三类文件**
- 同源治理包(与 hikos-gamedev / krow-kad 同源,Krow-labs 便携治理包 `krow-labs-governance-core/1`):`scripts/check_constitution.py` `lint_governance.py` `lint_workflows.py` `lint_secret_scan.py` `check_pr_deletions_declared.py` `lint_enforce_start.py`。**不在本仓单独改判据**——要改去同批改遍各仓;本仓差异只写 `docs/governance/kit.yaml` / `scripts/data/*.json`。
- 本仓独立闸(若有):改判据必须同 PR 改病理形态用例(坏实现能过全部健康用例、过不了它)。
- 宪法块(`AGENTS.md` 的 `<!-- krow:constitution:begin/end -->`):不改;红了去把各仓改齐,不改哈希将就。
2. **required check 与分支规则同日同步**:`.github/required-checks.txt` 每行逐字等于某个 `on: pull_request` 工作流里 job 的 `name:`(G11);增删 required check 要同一天改 GitHub ruleset `main`(admin 操作,写进 PR 正文谁来改)。新闸优先接进**已经是 required** 的 job「governance lint」(不新增 check 名 = 不动分支规则、当天 enforce、不卡别人在途 PR)。
3. **新闸 enforce 起步**(宪法 §0.2 F):不写 `continue-on-error: true`、不 `|| true`、不「先 notice 后绿」。确需软化:同一步骤块内写 `enforce-by: YYYY-MM-DD`(≤ 30 天,到期即红)/ `retire-when: <条件>` / `not-a-gate: <理由>`,`scripts/lint_enforce_start.py` 守。
4. **workflow 卫生**(`scripts/lint_workflows.py` W1–W6):每个 job `timeout-minutes`;顶层或每 job `permissions`;PR 工作流 `concurrency.cancel-in-progress: true`;新 workflow 文件名登记进 `CONTRIBUTING.md` CI 表;`workflow_run.workflows` 写目标 `name:` 逐字原文;required job 所在工作流的 `pull_request` 不带 `paths:` 过滤。
5. **AGENTS.md 预算**:宪法外 ≤ 150 行(G1 软 120 / 硬 160)。要加的内容先问「90% 的会话需要它吗」:否 → 进 `.cursor/rules/*.mdc` 或 `docs/governance/`,AGENTS.md 只留一行指针。灵魂关键词在 `kit.yaml invariants`,删关键词要同 PR 改它并在正文说明理由。
6. **新 `.mdc`**:frontmatter 要 `description` + `globs`(逗号分隔字符串)或 `alwaysApply: true`;`globs` 必须匹配到真实文件;在 `AGENTS.md` 登记文件名(G2,不登记 = 不存在)。
7. **元规则改动独立 PR**:`AGENTS.md` / `.cursor/rules/` / `.github/` / `scripts/` / `docs/governance/` 的改动不与业务改动混;治理 PR 自身要先在分支上看到新增 / 改动的 workflow **全绿**再合,admin merge 是兜底不是常规。
8. **删除要留痕**:PR 删掉的文件逐条写进正文(`scripts/check_pr_deletions_declared.py`,PR-only);退役模块在 `docs/governance/decisions.md` 点名(G9)。
9. **开火不留账是红线**(宪法 §0.2 I):治理 PR 不碰发布 / 部署 workflow 的开火语义;需要发布走本仓既有发布机制并在 PR 里写明谁、为什么。
29 changes: 29 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# 跨平台字节保真(与 krow-kad / hikos-gamedev 同一做法;母仓 line-ending.mdc:读时归一 LF、写回原样,禁整文件 CRLF↔LF 返工)。
* text=auto eol=lf

# 二进制:不判定、不转换、不 diff。
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.webp binary
*.ico binary
*.pdf binary
*.whl binary
*.tar binary
*.gz binary
*.zip binary
*.woff binary
*.woff2 binary
*.ttf binary
*.otf binary
*.glb binary
*.gltf binary
*.mp3 binary
*.mp4 binary
*.wav binary
*.jar binary
*.so binary
*.dylib binary
*.dll binary
*.exe binary
53 changes: 53 additions & 0 deletions .github/ISSUE_TEMPLATE/configure-required-secret.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
name: 配置仓库 secret(运维任务)
about: 申请持有者给本仓配置 CI 用的 GitHub repo secret(如 KAS_READ_TOKEN、CR_RO_* / CR_PUSH_*)。值只经 gh secret set,不经信件、不进代码。
title: "[ops] 配置 secret: <SECRET_NAME>"
---

<!-- 母仓 aullik5/krow .github/ISSUE_TEMPLATE/configure-required-secret.md 在本仓的精简版。
宪法 §0.2 E:以「对方不给 X」为前提做设计,必须附一次指名道姓的请求——这张单就是那次请求。 -->

## 目标 secret

**Secret 名**:`<SECRET_NAME>`

**类别**(勾选):

- [ ] PR 必配:required check 要它才能真正跑(缺了 = 空绿,`scripts/lint_enforce_start.py` 的 `enforce-by` 到期转红)
- [ ] 构建 / 发布必配:`agent-image.yml` / `auto-tag-on-version-bump.yml` 要它
- [ ] 按需:缺失时对应步骤明确跳过并在 summary 里写明

**影响 workflow**(文件名 + job):

- `<workflow>.yml` :: `<job name>`

## 当前状态

```bash
gh secret list -R Krow-labs/hikos-gamedev | grep <SECRET_NAME>
# 粘贴实际输出(只有名字和时间戳,不会显示值):
```

- [ ] 未配置
- [ ] 已配置但需轮换 / 权限不够

## 配置步骤(持有者做)

```bash
# 值从持有者本机 / 密码管理器直接进 GitHub,不经聊天、不经信件、不进任何 git-tracked 文件
gh secret set <SECRET_NAME> -R Krow-labs/hikos-gamedev
gh secret list -R Krow-labs/hikos-gamedev | grep <SECRET_NAME>
```

对 `KAS_READ_TOKEN`:一个对 `Krow-labs/krow-agent-service` 只读(`contents: read`)的 fine-grained PAT 或机器人 token 即可;它只用于 `governance.yml::teammate plugin tests + K1–K9` 的 sparse-checkout。

## 验证(关单前)

- [ ] `gh secret list` 里有它
- [ ] 影响的 workflow 在 main 上手动 `gh workflow run` 一次:对应 job 真正跑了(log 里没有 "未配置 / skipped")
- [ ] 若 `governance.yml` 里为它写过 `enforce-by:`,同 PR 把该步骤改回 enforce 并写 `enforce-by-done: <日期>`

## 注意

1. **永不**把明文 secret 贴进 issue / PR / 评论 / 站内信 / 大厅。
2. 推荐专属机器人账号 / 专属 token,审计轨迹干净、额度独立。
8 changes: 8 additions & 0 deletions .github/required-checks.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# 默认分支 `main` 的 required status checks —— 仓内镜像(与 krow-kad / hikos-gamedev 同一做法)。
# 真正的事实在 GitHub 分支规则里;本文件是它在仓内的镜像,两边必须一起改(同一天)。
# 一行一个 check 名,逐字等于某个带 `on: pull_request` 的 workflow 里 job 的 `name:`;# 开头是注释。
# scripts/lint_governance.py G11 逐条核对;scripts/lint_workflows.py W6 另核这些 job 所在 workflow 的 pull_request 不带 paths 过滤。
# 2026-11-08 Krow-labs 全仓对齐(任务 8393887e):治理闸都在「governance lint」里;新增 check 名时先改分支规则再改本文件。
constitution
governance lint
test
80 changes: 80 additions & 0 deletions .github/workflows/governance.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# 治理 CI(Krow-labs 便携治理包 krow-labs-governance-core/1;基准 aullik5/krow@30b5504f 的 lint.yml::governance-invariants /
# secret-scan / test-naming 与 pr-base-guard.yml 在本仓的落法;任务 8393887e)。
# 新闸全部 enforce 起步;存量 workflow 的 W1–W3 用 scripts/data/workflows_baseline.json 棘轮收编(只降不升)。
name: governance
on:
pull_request:
push:
branches: [main]
workflow_dispatch:

concurrency:
group: governance-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

env:
PIP_DISABLE_PIP_VERSION_CHECK: "1"
PYTHONUTF8: "1"

jobs:
constitution:
name: constitution
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: "3.13" }
- name: TURBO 宪法块逐字一致 + 本仓部分 ≤150 行
run: python scripts/check_constitution.py

governance:
name: governance lint
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: actions/setup-python@v5
with: { python-version: "3.13" }
- run: pip install pyyaml pytest
- name: 治理脚本自测(每道闸先证明自己拦得住、放得过)
run: |
python -m pytest scripts/tests/test_lint_workflows.py scripts/tests/test_lint_secret_scan.py scripts/tests/test_check_pr_deletions_declared.py scripts/tests/test_lint_governance_g11.py -q -p no:cacheprovider
python scripts/test_lint_enforce_start.py
- name: G1–G11(非组员仓只有 G1 / G2 / G10 / G11 有主体)
run: python scripts/lint_governance.py
- name: W1–W6 workflow 卫生(存量基线只降不升)
run: python scripts/lint_workflows.py
- name: enforce 起步闸(warning-only 必须带到期日;enforce-by 不过期、不超 30 天)
run: python scripts/lint_enforce_start.py
- name: secret scan(git-tracked 文件禁真凭证)
run: python scripts/lint_secret_scan.py
- name: PR base 必须是 main(base≠默认分支的 PR 其余 workflow 一条都不跑;叠 PR 下层被 squash 后上层永久失去落地路径却照样显示 MERGED)
if: github.event_name == 'pull_request'
env:
BASE: ${{ github.base_ref }}
run: |
if [ "$BASE" != "main" ]; then
echo "::error::本 PR 的 base 是 \`$BASE\`,不是 \`main\`。改法:先 rebase 到 origin/main,再 gh pr edit <PR号> --base main"
exit 1
fi
echo "base = main"
- name: 取全量历史(PR-only 闸要算 merge-base)
if: github.event_name == 'pull_request'
env:
BASE: ${{ github.base_ref }}
run: |
if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then git fetch --no-tags --unshallow origin; fi
git fetch --no-tags origin "+refs/heads/$BASE:refs/remotes/origin/$BASE"
- name: PR 正文落盘(走 env,不把作者可控文本直接展开进 shell)
if: github.event_name == 'pull_request'
env:
PR_BODY: ${{ github.event.pull_request.body }}
run: printf '%s' "$PR_BODY" > "$RUNNER_TEMP/pr_body.md"
- name: 删除必须在 PR 正文里逐条写明
if: github.event_name == 'pull_request'
run: python scripts/check_pr_deletions_declared.py --base "origin/${{ github.base_ref }}" --body-file "$RUNNER_TEMP/pr_body.md"
Loading
Loading