Skip to content

docs(maintainer): handoff for 2026-09-16 - #1789

Merged
Ikalus1988 merged 2 commits into
mainfrom
docs/handoff-2026-09-16
Sep 16, 2026
Merged

docs(maintainer): handoff for 2026-09-16#1789
Ikalus1988 merged 2 commits into
mainfrom
docs/handoff-2026-09-16

Conversation

@Ikalus1988

@Ikalus1988 Ikalus1988 commented Sep 16, 2026 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Owner

User description

交接文档：今天落了什么、什么在途、以及需要人来做的六件事。

需要人介入的部分（摘要）：

  1. /adopt 的首次真实使用 —— Add lesson: Gemini model ID naming and parameter constraints across providers #1746–Add lesson: LLM god-moding prevention in roleplay #1750 的内容是好的，只缺 DCO 签核；不要收养 fix: resolve #1652 - [Bounty][$0][Lessons] 把 intake #1553（alembic upgrade 失败）转成课程 #1656（骨架课程过不了结构门禁）。
  2. 首个端到端自动合并 —— feat(ci): an opt-in auto-merge channel for lesson pull requests #1781 的通道已上线但一次都没真的合过；收养出来的同仓 PR 正好可以打 auto-merge-lesson 标签验证它。
  3. feat(lesson): alembic upgrade failure diagnosis #1713–feat(lesson): write success but data missing — silent failures #1716 改一行 provenance 即可合并；对方不响应时需要决定关闭还是补写。
  4. PAT 可选 —— 让 fix-dco.yml 支持 fork；不建也行，/adopt 就是无密钥路径。
  5. worker 部署后确认 GET /api/search-signals/stats 返回 200 且在增长 —— 那是"提效"缺的分母。
  6. 策略判断 —— 外部课程 PR 是否默认打 auto-merge-lesson（现在是纯手动 opt-in）。

同时记录了这轮的流程教训：并行 Agent 改同一文件会搅在一起（编辑守护能发现，但整合要按 hunk 拆）；用桩 gh 回放 11 个场景全部通过、真上线却因为 gh api user 对 App token 返回 403 把每个 PR 染红——桩能验证逻辑，验证不了授权；以及"本地过的测试"因为证据在作者机器的 gitignored 目录里而在 CI 失败。

另附本机 git 通道的现状与撤销 deploy key 的一行命令。

PR Type

Documentation

Description

  • Adds handoff document for 2026-09-16

  • Records landed PRs and in-flight work

  • Lists 6 items needing maintainer intervention

  • Captures process lessons and known risks

Diagram Walkthrough

flowchart LR
  A["Pipeline status"] --> B["Landed today"]
  A --> C["In flight"]
  A --> D["Needs human"]
  B --> E["provenance gate / DCO / auto-merge"]
  C --> F["#1786 / #1787 / #1788 / #1783"]
  D --> G["6 maintainer decisions"]
  E --> H["Next steps & risks"]
  F --> H
  G --> H
Loading

File Walkthrough
Relevant files
Documentation
handoff-2026-09-16.md
Add maintainer handoff document for 2026-09-16                     

docs/maintainer/handoff-2026-09-16.md

  • New 80-line handoff document for the 2026-09-16 transition
  • Records what landed, what is in flight, and six items needing a human
  • Documents process lessons (parallel agents, stub-vs-real auth,
    local-only evidence)
  • Lists known risks (auto-merge blind spots, audit false-red, local git
    channel)
 +80/-0   

@Ikalus1988
docs(maintainer): handoff for 2026-09-16
6044639 
Records what landed, what is in flight, and — the part that matters for a handoff — the six
things that need a human rather than another agent:

1. the first real `/adopt` run (#1746–#1750, and explicitly *not* #1656, whose lesson fails the
   structural gate);
2. the first end-to-end auto-merge once an adopted PR exists, since the channel from #1781 is
   live but has never actually merged anything;
3. what to do about #1713–#1716 after their provenance fix;
4. whether to create the PAT that would make `fix-dco.yml` fork-capable (optional — `/adopt` is
   the no-secret path);
5. confirming `GET /api/search-signals/stats` returns 200 and grows after the worker deploys,
   because that endpoint is the denominator the efficiency claim has been missing;
6. the policy call on whether external lesson PRs get `auto-merge-lesson` by default.

Also records the process lessons of this stretch, because they cost real time: parallel agents
editing one file entangle the diff (the edit guard catches it, but integration means splitting by
hunk); a stub-`gh` replay of eleven scenarios passed while the real workflow went red on every PR
because `gh api user` returns 403 for an App installation token — a stub can verify logic, not
authority; and a test that passes locally can fail in CI because its evidence lives in a
gitignored directory on the author's machine.

Signed-off-by: Ikalus1988 <136884451+Ikalus1988@users.noreply.github.com>
@Ikalus1988 Ikalus1988 added area:docs docs-only Only documentation files changed shape-safe labels Sep 16, 2026
@github-actions

github-actions Bot commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶

1746 - Partially compliant

Compliant requirements:

  • None

Non-compliant requirements:

  • None of the lesson content requirements (this PR is a handoff document, not the lesson itself)

Requires further human verification:

1750 - Partially compliant

Compliant requirements:

  • None

Non-compliant requirements:

  • None of the lesson content requirements (this PR is a handoff document, not the lesson itself)

Requires further human verification:

1656 - Partially compliant

Compliant requirements:

  • None

Non-compliant requirements:

  • None of the lesson content requirements (this PR is a handoff document, not the lesson itself)

Requires further human verification:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 Security concerns

Infrastructure Detail Exposure (minor):
The handoff document includes a specific deploy key ID (163489824) and the API endpoint pattern for revoking it. The key ID is a public identifier and not a secret credential, so no credentials or private keys are leaked. The concern is purely about the practice of exposing operational infrastructure identifiers in public documentation, which provides reconnaissance value to potential attackers. No exploitable vulnerability is introduced.

⚡ Recommended focus areas for review

Ticket-PR Association

All three provided tickets (#1746, #1750, #1656) describe lesson deliverables, but this PR is a maintainer handoff document that does not implement any of those lessons. The handoff document references these issues by number in its advisory text (recommending /adopt for #1746 and #1750 once DCO is signed, and explicitly recommending against adopting #1656), but does not contain the lesson content itself. The tickets appear to be associated with this PR in error - they should be linked to their respective lesson PRs, not to this meta-document.

 
# Handoff —— 2026-09-16（自动合并通道、provenance 门禁、四个工作流立项与在途）

> 面向下一个接手的人（或下一个 session）。本文件只写**当前事实 + 需要人决定的事**，不重复设计文档。
> 相关文档：`docs/maintainer/blueprint-and-strategy-review-2026-09-16.md`（战略审视）、
> `docs/maintainer/issue-pr-status-2026-09-16.md`（PR/issue 现状快照）、
> `ROADMAP.md`（唯一对外路线图，含 2026-09-16 更新章节）。

---

## 1. 一句话状态

**课程生产线的机械部分基本建成**：结构门禁 → provenance 门禁 → DCO → 可选自动合并；fork 贡献有一条不依赖新密钥的收养路径。
**仍然缺的是度量**：命中率的分母刚做完（待合并），"能提效"目前仍无数字；多 agent 协同仍不是功能，只是"多个 agent 读同一个库"。

---

## 2. 今天落地（已合并）

| PR | 内容 | 关键提交 |
|---|---|---|
| #1768 | **provenance 门禁**：占位符 / 确认 404 失败；新增课程的 E2/E3 必须有可解析来源 | `152d0ff16` |
| #1771 | 门禁盲区：JSON frontmatter 的带引号键此前完全读不到 | `280550b87` |
| #1773 | 用 open-code-review 审出的**门禁自身漏洞**：SSRF（云元数据/CGNAT/IPv6）、令牌外泄给每个外链、开放重定向 + 三个解析洞 + Python 安装器 `"allow": "all"` 崩溃 | `4751461fe` |
| #1774 | 安装器：备份保留第一份、Hermes `.env` 补 `chmod 600`、`--verify` 说出失败原因、键序无关比较 | `87e19c16c` |
| #1770 | **近义词表**：150 条带取证 + 离线评测（中文问句 top-1 40%→70%，零回退）+ 根因（worker tokenizer 丢弃中文） | `c3e80e198` |
| #1776 | 热修：`main` 变红——测试引用了只在作者机器上存在的 gitignored 文件；断言改为 `git ls-files --error-unmatch` | `b2543dcab` |
| #1781 | **课程 PR 自动合并通道**（带 `auto-merge-lesson` 标签 + 全绿 + 只改 `lessons/`） | `11ac11c7a` |
| #1769 | 路线图更新（旧条目 39 行裁定）+ PR/issue 现状快照 | `171698fef` |
| #1766 | 蓝图与战略审视（五层拼图 / 四类用户 / 飞轮 / 十条最薄弱假设） | `e07844b6d` |
| 其他 | #1762（安装器放行只读工具 + 祈使式规则块）、#1764（PyYAML 守卫）、#1765（忽略生成的 `voice/`）、#1646（贡献者的 workflow 检查器，credit 保留） | — |

外部：`@misaka-net/misakanet-setup@0.5.3` 已发布；个人站点与 profile README 已更新（含新 blog《Five Failures That Passed Every Check》）。

## 3. 在途

| 项 | 状态 |
|---|---|
| **#1786** `/adopt` fork 收养流程 | PR 开着，等 CI 绿合并（18 项测试；dry run 已对真实 PR #1656 跑通） |
| **#1787** 语音钩子 → 注意信号路由 + 桌面通知 | PR 开着，等 CI 绿合并（28 项测试；cue 只作查表键，命令全部是文件内字面量） |
| **#1788** 自动合并通道的 403 热修 | PR 开着（`gh api user` 用 App token 必然 403；已改常量 + `gh_read` 防御 + 作业级 `continue-on-error`） |
| **#1779** 命中率分母 | Agent 已完成，**待整合**：与 #1783 在 `workers/register-proxy-sw.js` 里交错 |
| **#1782** `--report --strict` 卡口 | Agent 已完成，**待整合**：与 #1783 在 `packages/misakanet-setup/bin/misakanet-setup.mjs`、`workers/misakanet-setup.test.mjs` 里交错 |
| **#1783** 结构化课程字段（`summary_plain`/`trigger`/`verify`） | Agent 仍在跑（最后一个） |
| **#1780** 接线近义词表 | 排队：等 #1779 合并（同文件另一区域） |
| **#1784** 企业部署 `--silent`/`--report-json` | 排队：等 #1782 合并（同文件） |

**整合方式已定**：#1783 落地后，把三者的改动**按 hunk 拆开**，各自开 PR、各自跑测试，不把三件事塞进一个 PR。

## 4. ⚠️ 需要维护者（人）介入的事

1. **`/adopt` 的首次真实使用**：#1746–#1750 五个课程 PR 的内容是好的，只缺 DCO 签核（fork PR 的机器人推不动）。流程是：等 #1786 合并 → 在其中一个 PR 上评论 `/adopt`（看计划）→ 再评论 `/adopt --apply`。
   **不要收养 #1656**：它是 519 字节骨架，课程本身过不了结构门禁，收养只会把一个本该被拒的 PR 合并进来。
2. **首个自动合并的端到端验证**：收养产生的新 PR 是同仓分支、签核齐备、只改 `lessons/`，**正好可以打上刚创建的 `auto-merge-lesson` 标签**，验证 #1781 的通道真的能自己合并。这也是目前唯一缺的"通道上线但没跑过"的一环。
3. **#1713–#1716 的选择**：同一作者的四个课程 PR，`source:` 全部指向一个 404 仓库（`modelcontextprotocol/mcp-memory-service`），已各留 request-changes。他们改一行 provenance 即可合并；若对方不再响应，需要决定是关掉还是由我们补写。
4. **PAT（可选）**：若要 `fix-dco.yml` 直接支持 fork，需要维护者建一个 secret（fine-grained token 或 PAT）。**不建也行**——#1786 的 `/adopt` 就是无密钥路径。
5. **worker 改动上线后的线上确认**：#1779 会新增 `GET /api/search-signals/stats`（只读、只回 `solved` + `created_at`）。合并即自动部署，**部署后请确认这个端点返回 200 且行数在增长**——它是"提效"这个数字的分母，没有它 B1（首次报错自动触发）无法评估。
6. **策略问题（只需一句判断）**：是否默认给外部课程 PR 打 `auto-merge-lesson`？现在的设计是**只有维护者手动打标签才启用**，避免"没人看过就进语料"。

## 5. 已知问题与风险

- **`auto-merge-lesson` 通道的三个已知盲点**（写在 `docs/maintainer/auto-merge-lessons.md`）：`check_suite` 事件对 Actions 自建 suite 可能不触发（真正承重的是 `synchronize`/`ready_for_review`）；测试矩阵**整批未上报**时判定看不见；`CHANGES_REQUESTED` 的过期判定不比对 SHA（偏严）。
- **门禁查不了语义真伪**：一个真实但与课程无关的链接照样通过。provenance 门禁挡的是最廉价、量最大的一类污染。
- **`audit` 假红机制**：它的 pytest 步骤带 `continue-on-error`，step 显示 success 而 `steps.pytest.outcome` 是 failure → 报"Test suite failed"却不显示失败用例。**判据：`audit` 红 + `test (...)` 矩阵绿 ⇒ 去读 job 原始日志。**
- **本机 git 通道**：`github.com:443` 被墙（7 个官方 IP 全不通），`api.github.com` 通。已用**仓库级 deploy key（写权限，id 163489824）** + `ssh.github.com:443` 恢复原生 push（`git fetch/push` 可用）。要撤销：`DELETE /repos/Ikalus1988/MisakaNet/keys/163489824`。
- **本机工作树曾有 stash 备份**：`stash@{0}`（同步前的旧快照）；`main` 已与 `origin/main` 对齐。

## 6. 流程教训（这一轮真正的收获）

1. **并行 Agent 改同一个文件会把 diff 搅在一起**。编辑工具的"文件已变"守护让它**被发现**而不是被静默覆盖，但代价是整合时要按 hunk 拆。下次：一个文件一个 owner，或用独立 worktree。
2. **桩回放查不出权限类错误**。自动合并通道的 `run:` 步骤用桩 `gh` 回放了 11 个场景全部通过，上线后却因为 `gh api user` 对 App token 返回 403 而把每个 PR 染红——桩能验证逻辑，验证不了**授权**。
3. **"测试在本地过了"不等于它会过**：测试引用了只在作者机器上存在的 gitignored 文件；断言已改成 `git ls-files --error-unmatch`，并做了反证（改回旧路径必失败）。
4. **门禁必须被对抗性地读一遍**：provenance 门禁当天就被 open-code-review 找出三个安全洞；`too_large` 会跳过最大的文件（`workers/register-proxy-sw.js` 4475 行已切片补扫，结果在 issue #1775）。
5. **只在有证据时失败**：超时/DNS/限流/5xx 一律记 `unknown` 且不让构建变红——否则门禁一周内就会被绕过。

## 7. 建议的下一步（按顺序）

1. 合并 #1786/#1787/#1788；#1783 落地后按 hunk 整合 #1779/#1782/#1783。
2. 启动 #1780（接线近义词表，统一 `misakanet/search/engine.py::_expand_query` 的旧 `_SYNONYM_MAP` 与 `data/query-aliases.json`）与 #1784（企业部署）。
3. 用 #1746–#1750 之一跑通"`/adopt` → 打标签 → 自动合并"，把整条机械通道验成事实。
4. worker 部署后确认 `/api/search-signals/stats` 有数据；有分母之后再评估 B1。
Infrastructure Detail Exposure

The handoff document exposes a specific deploy key ID (163489824) along with the API endpoint pattern used to revoke it. The key ID itself is a public identifier (not a secret credential), so this is not a credential leak. However, embedding operational infrastructure details - including the exact revocation endpoint - in a public-facing document is suboptimal hardening practice. Consider whether such operational specifics belong in a public handoff document or should reference an internal runbook instead.

 
- **本机 git 通道**：`github.com:443` 被墙（7 个官方 IP 全不通），`api.github.com` 通。已用**仓库级 deploy key（写权限，id 163489824）** + `ssh.github.com:443` 恢复原生 push（`git fetch/push` 可用）。要撤销：`DELETE /repos/Ikalus1988/MisakaNet/keys/163489824`。

@github-actions

github-actions Bot commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

PR Code Suggestions ✨

No code suggestions found for the PR.

@Ikalus1988

Ikalus1988 commented Sep 16, 2026

Copy link
Copy Markdown
Owner Author

🧾 Audit Report — PR #1789 (6044639)

📊 Quality Score

⚠️ Quality score unavailable; continuing with hard gates.

🔏 DCO Audit

✅ All commits signed-off.

📏 PR Size

Metric Value
Files Changed 1
Lines Added 80

🔐 Secret Scan

✅ No hardcoded secrets detected.

📦 Dependency Audit

⏭️ Skipped; no Python/JS dependency files changed.

🧪 Test Suite

✅ PASS — 53% coverage

📋 Lesson Schema

✅ All lessons valid.

⚖️ Verdict

✅ All gates passed. Ready for merge.

Scope: full | Triggered by 6044639 | View run

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs		 misakanet-web fdcb4eb Commit Preview URL

Branch Preview URL		 Sep 16 2026, 05:27 PM

@Ikalus1988
Ikalus1988 merged commit 9f422e0 into main Sep 16, 2026
1 check passed
@github-actions

github-actions Bot commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

✅ Merged! Thanks again, @Ikalus1988.

docs(maintainer): handoff for 2026-09-16 (+80 lines, 1 files)

Quick question — did any MisakaNet lesson help you this time?
→ Share feedback

No need to reply if nothing comes to mind. ⚡

@github-actions

github-actions Bot commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

🎉 Merged — Thank you!

Your contribution has been merged into main.

PR: #1789 — docs(maintainer): handoff for 2026-09-16

What's next:

  • Your code is now part of MisakaNet's failure-lesson corpus (now 393 lessons)
  • Feel free to pick up another issue labeled good first issue or status: competition
  • Questions? Ask in this thread or open a Discussion

Welcome to the MisakaNet contributor community! 🧠

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

area:docs docs-only Only documentation files changed Review effort 2/5 shape-safe

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Ikalus1988