docs(cr-checklist): fold task #32 + task #35 sediment — 7 lessons + Lesson #14#1916
Merged
Merged
Conversation
…esson #14 Phase A 全闭环 follow-up sediment（task #32 Phase A close 后启动）。 fold 7 lesson sediment 进 § 四（task #32 + task #35 多轮迭代实证累计）+ fix-forward task #45 PR #1908 NIT defer (mcp-api.md "Phase A 后" → "当前已携带"， per architect msg=04c7962e Option B + dongdong msg=1c08ac8a)。 § 四 新增 7 lesson: - Lesson #12 v6 sub-form (v6.1 function / v6.2 endpoint / v6.3 data type scope walk) — 架构师 msg=9c5c32d1 升级，task #36 PR #1899 fix-forward² L148 case 实战 surface - Lesson #12 v7 (caller signature → backend schema → runtime fallback 三层 grep) — task #34 rerank 调研 huangheng msg=e539848f own-up + 架构师 msg=b12fec5d thoroughness=very thorough trace 实证 - Lesson #12 v7.1 (composite key invariant) — task #32 spec PR #1905 Weston msg=7500e57d BLOCKER catch + huangheng + 架构师 double own-up - Lesson #12 v7.1 sub-form (backend 投影层 + acceptance 跨 endpoint chained chain 双层 verify) — 架构师 msg=f04b36a8 升级，PR #1909 backend textbook (`8d5ffa97`) + PR #1912 acceptance textbook (`eb2a805b`) 配对 - Lesson #13 v2.1 (import-level dual-side rewrite — 删 source 必删 obsolete test 文件 / 函数) — task #17 PR #1884 first + task #36 PR #1899 fix-forward¹ second - Lesson #13 v2.2 (value-level dual-side rewrite — 删 source 字段 / 数据必 同步 update stale assertion / count) — task #36 PR #1899 fix-forward² L103/L108 first + task #47 PR #1910 contract test second - Lesson #13 v3 (boundary 不重复事实保证 invariant，只覆盖可能 drift 的 contract) — 架构师 msg=036dd8b2 升格，task #46 PR #1906 first - Migration chain 时序 invariant (enum hard-cut PR 必先 chain DELETE FROM 旧 enum value migration) — task #47 PR #1910 first (`3c7d2f81b5e9` chain 在 `a8f4c2d9e1b7` 后) - Lesson #14 (架构 invariant 删除多轮迭代收尾 — sweeping cleanup directive 单 PR 无法一次性 cover，多轮 grep gate verify + fix-forward task 是工程 常态) — task #35 6 轮 fix-forward 实证 first (PR #1899/#1897/#1898/ #1906/#1910/#1911 + task #40 final 验收) § 六 sediment 引用追加: - PR #1909 (`8d5ffa97`) Lesson #12 v7.1 backend 层 textbook - PR #1912 (`eb2a805b`) Lesson #12 v7.1 acceptance 层 textbook - task #35 6 轮 fix-forward 收尾 Lesson #14 first-application demo § 八 修订记录追加本次 commit timeline。 mcp-api.md L88 fix-forward (per dongdong msg=f1975615 + 架构师 msg=04c7962e Option B): "task #32 Phase A 后" → "当前已携带（task #32 Phase A 落地， PR #1909 + PR #1912）"。Phase A 全闭环后用户面文档现状准确。 来源 directive: PM msg=0129c3c5 phase A close 后启动 follow-up 子 PR + 架构师 msg=62e58a18 Phase A close 后立即启动 directive。
3 tasks
earayu
added a commit
that referenced
this pull request
Apr 29, 2026
Per 冬柏 msg=f2c0615b: msg=14a00712 was never sent; slock search returns 0 hits, so citing it in a permanent doc would leave a dangling reference that future grep / verification cannot resolve. Drop the two suspect msg IDs from §4 and replace with the concrete PR forensics list already cited in §1 (task #17 PR #1893 / #1885 / #1886 / #1890 / #1891 / #1899). Cross-link to the Lesson #12 v5 sediment in cr-review-checklist § 四 (PR #1916, sha b3c3a0e) for the trust-framing anti-pattern itself, which is verifiable. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
earayu
added a commit
that referenced
this pull request
Apr 29, 2026
…1919) * docs(ci): codify provider matrix flake handling policy (task #33 P0) Add ``docs/zh-CN/architecture/ci-flake-policy.md`` (147 lines, docs only) formalising the rules under which a Nebula / Neo4j ``e2e-http-provider`` single-shape failure can be human-approved, vs. always requiring a real fix or rerun. Why this exists: - Recent 20 runs show Nebula/Neo4j fail rate ~15% vs Lite 5% (3x). - Cross-PR forensics (task #17 PR #1893/#1885/#1886/#1890/#1891/#1899) attribute the gap to a single known-signature flake at ``aperag/domains/retrieval/runtime.py:1056`` (``ValidationException: Model specification is required for agent runtime v3``) — independent of the PR diff (different runs same commit produce different outcomes). - Until the root cause is fixed, reviewers were applying the rule verbally on a case-by-case basis. Codifying it removes that inconsistency without losing the deployment signal those shapes catch (e.g. the task #17 worker DI seam regression). Policy gist: 1. Lite must always be green — no human approval allowed. 2. Single Nebula/Neo4j failure may be approved iff: - failure log contains ``runtime.py:1056`` and the canonical ``Model specification is required`` text; - the PR touches none of: ``aperag/domains/{retrieval,model_platform,llm}/``, ``aperag/mcp/``, ``aperag/indexing/``, ``.github/workflows/e2e-http-*.yml``, ``tests/e2e_http/``, ``deploy/aperag/``; - the approving reviewer cites the specific run/job id, the log fragment, and the diff-zero-overlap evidence in the PR comment. 3. Other failure signatures (``PromptTemplateOps not wired``, probe failures, ``IK index not found``, timeouts, etc.) cannot use this exemption and must be fixed or rerun. 4. Approval implies someone owns the root-cause follow-up; lists the SRE / CR / architecture lanes responsible. Acks the ledger Planetegg surfaced in msg=46a0c5de and the trust-framing lesson huangheng sedimented in PR #1916 (Lesson #12 v5): once root cause is fixed, §2.2 of the doc is meant to be removed and the rate to converge to Lite's 5%. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(ci-flake-policy): correct path references + add short-term framing Three small fix-forward edits per Planetegg msg=d8196473 and huangheng msg=fc23e20c review: 1. ``aperag/domains/retrieval/runtime.py:1056`` → ``aperag/domains/agent_runtime/runtime.py:1056``. The known-signature actually originates from the Agent Runtime V3 turn module, not the retrieval pipeline. 2. The diff-zero-overlap §2.2 list now itemises both ``aperag/domains/agent_runtime/`` and ``aperag/domains/retrieval/`` separately (they were previously collapsed into one bullet) and corrects ``aperag/domains/llm/`` to ``aperag/llm/`` (the actual path; ``aperag/domains/llm/`` does not exist). 3. Add a one-line short-term-framing callout near the §2 header so the policy cannot be cited as a permanent license: human approval does not absolve root-cause investigation; §5 sunset criteria are the way out, not §2. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs(ci-flake-policy): replace dangling msg IDs with concrete PR list Per 冬柏 msg=f2c0615b: msg=14a00712 was never sent; slock search returns 0 hits, so citing it in a permanent doc would leave a dangling reference that future grep / verification cannot resolve. Drop the two suspect msg IDs from §4 and replace with the concrete PR forensics list already cited in §1 (task #17 PR #1893 / #1885 / #1886 / #1890 / #1891 / #1899). Cross-link to the Lesson #12 v5 sediment in cr-review-checklist § 四 (PR #1916, sha b3c3a0e) for the trust-framing anti-pattern itself, which is verifiable. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This was referenced Apr 29, 2026
earayu
added a commit
that referenced
this pull request
Apr 29, 2026
earayu
added a commit
that referenced
this pull request
Apr 29, 2026
….2/v7.3/v8 + #13 v3 (#1924) * docs(cr-checklist): fold task #30 A2/B1 sediment — Lesson #12 v6.4/v7.2/v7.3/v8 + #13 v3 application task #30 Phase A 全闭环后 follow-up 子 PR 2 (per PM msg=5debfb74 leverage B2 等 OpenRouter key wait window). fold 4 lesson sediment 进 § 四 (task #30 A2 + B1 + cross-PR cross-reviewer 独立 forensics 实证累计): - Lesson #12 v6.4 (function-self-verify ≠ aggregation-chain-verify) — helper 函数自身正确不等于 caller 在 aggregation/批处理/loop scope 应用正确. first-application: task #36 PR #1899 fix-forward² L148 endpoint scope. second-application: task #30 B1 PR #1923 commit `163b77c1` source_chunk_ids window-scoped fix. - Lesson #12 v7 second-application demos 累计 3 类 sub-form: - v7.1 composite key invariant (already sedimented PR #1916) - v7.2 Pydantic schema layer mandatory exposure — task #30 A2 PR #1921 KnowledgeGraphConfig 漏 2 字段 first-application - v7.3 cross-PR default value alignment — task #30 B1 PR #1923 response_format default 漂移 first-application - Lesson #12 v8 (fake guardrail anti-pattern) — guardrail 函数 signature 必须接 actual runtime data 不能仅 synthetic placeholder. task #30 A2 PR #1921 first iteration `_estimate_window_prompt_tokens` 硬编码 base_chunk_size=400 first-application + fix-forward `6d2db64`. - Lesson #13 v3 application demo (未实证 invariant 不预先锁) — type narrowing / value space cap pre-locking 反过来应用 v3. task #30 A2 PR #1921 NIT defer Literal vs Optional[str] first-application. § 六 sediment 引用追加 PR #1921 / PR #1923 / PR #1922 三 commit cross-link. § 八 修订记录追加本次 commit timeline + 4 lesson sediment 类别. 来源: PM msg=5debfb74 (B2 等 key wait window 推进) + ziang msg=f7dc20ef + Weston msg=9f356fe9 + ziang msg=c170ad75 + 黄章书 msg=cda4dc75 多 reviewer cross-check 独立 surface forensics trail. * fix(cr-checklist): NIT '3 周内' → '数小时内' (PR #1916 + A2/B1 同日 timeline)
5 tasks
earayu
added a commit
that referenced
this pull request
Apr 30, 2026
…audit (#1928) * docs(task-61): DB adapter compat spec v1 — vector + graph cross-impl audit Architect spec v1 起草 per earayu2 directive (msg=8b989470 / msg=2bad8e75 / msg=f26b703e) + PM 不穷 task #72 dispatch. Streaming evidence integration from 8 lanes: - huangheng msg=ed2f2973: 3 vector P0 candidates (cross-tenant / filter silent / collection init) - Bryce msg=8e895471 task #69: 11 vector findings (4 P0 + 3 P1 + 4 P2, including upgraded score normalization P0-V3/V4) - 冬柏 msg=3e93bb64 task #67: 3 missing Protocol method tests (bulk_upsert_entity_with_lineage_parts P0 + remove_relation_lineage P1 + list_entities P1) - chenyexuan msg=f298011e + PR #1926: workflow paths filter dead reference P0-W1 (in flight) - cuiwenbo msg=dfebf706 task #70: FE/UX 3 candidates (score, viz error vs empty, confidence_score) - Planetegg msg=db7fb085 + msg=41906f4 + msg=41665d7e task #65: alias resolution gather P2-S1 + Singapore QDRANT_MULTITENANT=True (no hot-fix needed) + env shape verify - ziang task #64 graph store audit (in_progress, will fold-in) - dongdong task #71 deploy/typed schema (in_progress, will fold-in) Spec structure: - §1 inventory by lane with file:line evidence - §2 缺口 by severity (P0 CRITICAL hot-fix candidate / P0 必修 / P1 允许差异 declare / P2 性能优化 / YAGNI) - §3 三层 design direction per Weston msg=85e527e3 framework - §4 sub-task dispatch (Phase A 8 lane parallel + Phase B per-P0 three-PR-pattern + Phase C P2 + Phase D PR #1926 unblock) - §5 acceptance: P0/P1 standards + boundary test gate + e2e + sample limitation免责 - §6 CR mandatory checklist citing Lesson #11-#16 family from PR #1916/#1924/#1922 sediment + new Lesson #16 candidate (workflow paths dead reference) Sample limitation: spec evidence from streaming surface, not huangzhangshu collected gap list — fix-forward amend after huangzhangshu lane completes + Bryce/ziang audit slice输出. Not blocking: PR #1925 task #30 B3 default=2, PR #1926 compat-test paths filter, Singapore 2pm release (env fix separate lane), task #31 graph node merge / task #33 P3 workflow gate. * docs(task-61): fix-forward Weston BLOCKER + 5 streaming integration Weston msg=13dd5e91 BLOCKER (score normalization severity drift): 保持 P0-V3+V4 P0 across §1.1 / §2.2 / §5.3 — score 方向是 caller 语义硬契约，不能在 PGVector/Qdrant 间显示反向。§2.2 加 P0-V3+V4 显式行 + §5.3 加 test_score_normalization_in_vector.py boundary test (跨 metric × 跨 adapter 全 6 cell parametrize). Streaming integrations (5 lane): 1. Bryce msg=23a2f514 P0-V1 first-principles 重新定性 — Qdrant legacy mode tenant isolation 是 collection name level 不是 query filter level (verify qdrant_connector.py:442-446)，下沉 P1-V4 defense-in-depth (legacy mode deprecation follow-up 候选). 2. Bryce msg=8e895471 11 vector findings — 4 P0 (cross-tenant 下沉 / filter silent / score V3+V4) + 3 P1 (collection init / batch atomicity / filter Or 语义) + 4 P2. 3. dongdong msg=4201465a + PR #1929 + cuiwenbo msg=bcec38ad — P0-D1 Helm worker Neo4j env missing (Singapore graph viz root-cause); P1-D1 e2e shape matrix gap; P1-D2 Nebula no Helm first-class; P1-D3 typed schema 缺 vector backend exposure. 4. chenyexuan NIT — Lesson #16 candidate cite added §6. 5. Planetegg msg=eb9de4b0 NIT — P2-S1 量化 max_nodes*2 default 1000→2000 / hybrid default 1000 max 5000; msg ID corrections §7 (msg=41665d7e Singapore multitenant verify, msg=eb9de4b0 P2-S1 quantification, dropped invalid msg=ec358a3e). 冬柏 PR #1927 commit b2234ae fold-in §5.3 (38 cases incl zero-side-effect + replay idempotency post-NIT). P0 list final: P0-V2 (filter silent, Bryce P0-A) + P0-V3+V4 (score normalization, Bryce P0-B) + P0-G1 (bulk_upsert, 冬柏 PR #1927) + P0-W1 (compat-test paths, chenyexuan PR #1926) + P0-D1 (Helm Neo4j env, dongdong PR #1929). * docs(task-61): § 3.1.1 historical residue cleanup per Weston msg=fdf04a69 NIT — strike old P0 hot-fix path (P0-V1 已下沉 P1-V4 per Bryce first-principles verify) * docs(task-61): final consistency cleanup per Weston msg=e414d3cf — line 14 count 4+3+4 to 3 P0 + 4 P1 + 4 P2; § 5.1 P0-V1 line removed; § 5.2 P1-V4 defense-in-depth boundary test added
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase A 全闭环 follow-up sediment（task #32 Phase A close 后启动 per architect msg=62e58a18 + PM msg=0129c3c5 directive）。
fold 7 lesson + Lesson #14 进
task-17-cr-review-checklist.md§ 四（task #32 + task #35 多轮迭代实证累计）+ fix-forward task #45 PR #1908 NIT defer (mcp-api.md"Phase A 后" → "当前已携带"，per architect msg=04c7962e Option B + dongdong msg=1c08ac8a)。2 文件 / 181 insertions / 3 deletions。
Sediment 内容
§ 四 新增 7 lesson（task #32 + task #35 多轮迭代实证累计）
8d5ffa97) + PR test(task-48): pin graph evidence_refs → read_document_chunk acceptance chain #1912 acceptance textbook (eb2a805b) 配对§ 六 sediment 引用追加
8d5ffa97) Lesson fix: socket reconnect bug #12 v7.1 backend 层 textbookeb2a805b) Lesson fix: socket reconnect bug #12 v7.1 acceptance 层 textbookmcp-api.md L88 fix-forward (NIT defer Option B)
task #32 Phase A 后→当前已携带（task #32 Phase A 落地，PR #1909 + PR #1912）。Phase A 全闭环后用户面文档现状准确。Test plan
lint-and-unit跑通（Lesson fix: socket reconnect bug #12 v4 mandatory gate 自身 dogfood）