Merge pull request #74 from CodeWithJuber/mintlify/1ff51f6b

Update from code changes: verify --deep statuses and completion gate

Author: CodeWithJuber

mintlify/ar/cli/quality.mdx

@@ -15,6 +15,19 @@ forge verify
 forge verify --deep       # multi-lens consensus (v0.19+)
 ```
 
+يُبلِّغ `forge verify --deep` عن `status` رباعي الحالات بدلًا من نجاح/إخفاق ثنائي:
+
+| الحالة           | المعنى                                                                                |
+| ---------------- | ------------------------------------------------------------------------------------- |
+| `PASS`           | اتفقت جميع العدسات **و** حالة اختبارات `forge verify` الأساسية هي أيضًا `PASS`.       |
+| `FAIL`           | أبلغت عدسة واحدة على الأقل عن إخفاق حقيقي.                                            |
+| `INCOMPLETE`     | لم تتمكن عدسة من الإنهاء (مهلة، أو تعطل، أو تبعية مفقودة) — تُعامَل كأنها غير مُثبَتة. |
+| `NOT_CONFIGURED` | لا توجد عدسات موصولة بهذا المستودع — لم يُفحَص شيء فعليًا.                            |
+
+`PASS` وحدها تُعتبر تحققًا. يرفض `--deep` عمدًا ترقية الإجماع إلى `PASS` عندما تكون حالة
+اختبارات `forge verify` الأساسية أي شيء غير `PASS`، بحيث يستلزم اجتياز الفحص العميق
+اجتياز الفحص الأساسي دائمًا.
+
 ## `forge scan`
 
 بوّابة المهارات — فحص مهارة أو خادم MCP بحثًا عن الحقن / RCE / التسريب قبل التثبيت.

mintlify/ar/concepts/cross-session-memory.mdx

@@ -46,10 +46,15 @@ description: "تثبيت الجلسة، وبوّابة الإكمال، ولقط
   `FORGE_STOPGATE=0` يوقفه.
 </Note>
 
+بالنسبة للجلسات التي غيّرت الشيفرة، تشترط البوّابة أيضًا **دليلًا اختباريًا** — إما ملف
+اختبار في فرق الجلسة، أو تشغيلًا طازجًا ناجحًا لـ `forge verify` مقابل التغييرات
+الحالية. لم تعُد لقطة `forge handoff` وحدها كافية لتجاوز فرع تغيير الشيفرة من البوّابة.
+
 قائمة الإصلاح تُشير إلى الأدوات التي تُنهي العمل:
 
 ```bash
-forge docs sync                      # sweep the diff for stale doc mentions
+forge verify                             # record the test evidence for code changes
+forge docs sync                          # sweep the diff for stale doc mentions
 forge handoff "<done>" --next "<next>"   # write the bounded session snapshot
 forge decide "<decision> — <reason>"     # record a choice so no session re-decides it
 ```

mintlify/ar/concepts/verification-gates.mdx

@@ -28,6 +28,19 @@ forge verify --deep       # multi-lens consensus — several independent checks
   تحقق مستقلة، لا عدسة واحدة فقط.
 </Note>
 
+يُبلِّغ `forge verify --deep` عن `status` رباعي الحالات، لا نجاح/إخفاق ثنائيًا:
+
+- `PASS` — اتفقت جميع العدسات **و** حالة اختبارات `forge verify` الأساسية هي أيضًا
+  `PASS`. هذه الحالة وحدها تُعدّ تحققًا.
+- `FAIL` — أبلغت عدسة واحدة على الأقل عن إخفاق حقيقي.
+- `INCOMPLETE` — لم تتمكن عدسة من الإنهاء (مهلة، أو تعطل، أو تبعية مفقودة). لم يُدحَض
+  شيء، لكن لم يُثبَت شيء كذلك.
+- `NOT_CONFIGURED` — لا توجد عدسات موصولة بهذا المستودع، فلم يجد `--deep` ما يفحصه.
+
+قاعدة أن `PASS` تستلزم `PASS` في الفحص الأساسي مقصودة: لا يمكن لإجماع عميق أخضر أن
+يتجاوز تشغيلًا أساسيًا أحمر، لذا فإن `INCOMPLETE` أو `NOT_CONFIGURED` على عدسة الاختبار
+الأساسية يُخفّض نتيجة الفحص العميق لتطابقها.
+
 ## عَلَم الرمز المُهلوَس — `forge atlas has`
 
 `forge atlas has <symbol>` هو فحص الهلوسة: إذا استدعى النموذج رمزًا ليس في الرسم البياني
@@ -83,6 +96,27 @@ forge harden               # gitleaks pre-commit + sandbox settings
   وقت الالتزام حتى يُصطاد العمل الجزئي أو غير المُتحقَق منه قبل أن يهبط.
 </Note>
 
+## بوابة الإكمال — الدليل الاختباري مطلوب
+
+لم تعُد بوابة إكمال مسار Stop (راجع
+[الذاكرة عبر الجلسات](/concepts/cross-session-memory)) تقبل تسليم الوكيل دليلًا على
+اكتمال تغييرات الشيفرة. بالنسبة لأي جلسة لمست شيفرة المصدر، تشترط البوابة **دليلًا
+اختباريًا حقيقيًا**:
+
+- ملف اختبار مُعدَّل في فرق الجلسة، **أو**
+- تشغيل ناجح طازج لـ `forge verify` مُسجَّل مقابل التغييرات الحالية.
+
+لا تكفي لقطة `forge handoff` وحدها لاجتياز البوابة — فهي تُسجّل النية، لا التحقق. إن
+غاب كِلا الدليلَين، تحجب البوابة مرة واحدة مع قائمة إصلاح:
+
+```bash
+forge verify                              # produce the test evidence
+forge handoff "<done>" --next "<next>"    # then snapshot the session
+```
+
+الجلسات التي لا تمس الشيفرة — كالتغييرات على التوثيق فقط، أو الإعدادات فقط، وغيرها —
+لا تتأثر؛ فمطلب الدليل الاختباري يُطلَق فقط حين يُغيّر فرق الجلسة الشيفرة فعلًا.
+
 ## فحوصات واجهة المستخدم — `forge uicheck`
 
 فحوصات UI حتمية، دون LLM ودون لقطات شاشة لأول ثلاث عدسات:

mintlify/cli/quality.mdx

@@ -15,6 +15,19 @@ forge verify
 forge verify --deep       # multi-lens consensus (v0.19+)
 ```
 
+`forge verify --deep` reports a four-state `status` instead of a plain pass/fail:
+
+| Status           | Meaning                                                                              |
+| ---------------- | ------------------------------------------------------------------------------------ |
+| `PASS`           | Every lens agreed **and** the core `forge verify` tests status is also `PASS`.       |
+| `FAIL`           | At least one lens reported a real failure.                                           |
+| `INCOMPLETE`     | A lens could not finish (timeout, crash, missing dependency) — treat as not proven.  |
+| `NOT_CONFIGURED` | No lenses are wired up for this repo — nothing was actually checked.                 |
+
+Only `PASS` counts as verified. `--deep` deliberately refuses to promote a consensus to
+`PASS` when the underlying `forge verify` tests status is anything other than `PASS`, so
+a green deep run always implies a green base run.
+
 ## `forge scan`
 
 Skill-gate — vet a skill or MCP server for injection / RCE / exfil before install.

mintlify/cn/cli/quality.mdx

@@ -15,6 +15,19 @@ forge verify
 forge verify --deep       # multi-lens consensus (v0.19+)
 ```
 
+`forge verify --deep` 汇报的是一个四态的 `status`，而不是简单的 pass/fail：
+
+| 状态             | 含义                                                                                  |
+| ---------------- | ------------------------------------------------------------------------------------- |
+| `PASS`           | 每一个视角都一致通过，**并且**核心 `forge verify` 的测试状态也是 `PASS`。             |
+| `FAIL`           | 至少有一个视角报出了真实的失败。                                                      |
+| `INCOMPLETE`     | 某个视角没能跑完（超时、崩溃、依赖缺失）—— 视为未被证明。                             |
+| `NOT_CONFIGURED` | 这个仓库没有接通任何视角 —— 实际上什么都没检查。                                      |
+
+只有 `PASS` 才算已验证。`--deep` 有意拒绝在底层 `forge verify` 的测试状态不是 `PASS`
+时把共识提升为 `PASS`，所以一次绿色的 deep 运行永远意味着一次绿色的
+base 运行。
+
 ## `forge scan`
 
 技能门 —— 在安装前审核一个 skill 或 MCP 服务器是否有注入 / RCE / 数据外泄风险。

mintlify/cn/concepts/cross-session-memory.mdx

@@ -45,10 +45,15 @@ Stop 路径上唯一有资格作出回应的 guard 是 `completion-gate.sh`
   也都放行（fail-open）。`FORGE_STOPGATE=0` 可以关掉它。
 </Note>
 
+对于动了代码的会话，这个门还要求提供**测试证据** —— 要么会话 diff 里有一个
+测试文件，要么针对当前变更有一次新鲜通过的 `forge verify`。仅凭一份
+`forge handoff` 快照，已经不足以清掉这个门的代码变更这一支。
+
 修复清单指向那些能收尾工作的工具：
 
 ```bash
-forge docs sync                      # sweep the diff for stale doc mentions
+forge verify                             # record the test evidence for code changes
+forge docs sync                          # sweep the diff for stale doc mentions
 forge handoff "<done>" --next "<next>"   # write the bounded session snapshot
 forge decide "<decision> — <reason>"     # record a choice so no session re-decides it
 ```

mintlify/cn/concepts/verification-gates.mdx

@@ -29,6 +29,19 @@ forge verify --deep       # multi-lens consensus — several independent checks
   独立的验证视角，而不只是一个。
 </Note>
 
+`forge verify --deep` 汇报的是一个四态的 `status`，不是二元的 pass/fail：
+
+- `PASS` —— 每一个视角都一致通过，**并且**核心 `forge verify` 的测试状态也是
+  `PASS`。只有这个状态才算已验证。
+- `FAIL` —— 至少有一个视角报出了真实的失败。
+- `INCOMPLETE` —— 某个视角没能跑完（超时、崩溃、依赖缺失）。什么都没被证伪，
+  但也什么都没被证明。
+- `NOT_CONFIGURED` —— 这个仓库没有接通任何视角，所以 `--deep` 无东西可查。
+
+`PASS` 蕴含 base 也是 `PASS` 这条规则是有意为之：一次绿色的 deep 共识永远
+不能跑赢一次红色的 base 运行，所以 base 测试视角上的 `INCOMPLETE` 或
+`NOT_CONFIGURED` 会把 deep 的结果同步降级。
+
 ## 幻觉符号标记 —— `forge atlas has`
 
 `forge atlas has <symbol>` 是幻觉检查：如果模型调用了一个不在代码图里的
@@ -84,6 +97,26 @@ forge harden               # gitleaks pre-commit + sandbox settings
   让部分完成或未验证的工作在落地之前就被拦住。
 </Note>
 
+## 完成门 —— 必须有测试证据
+
+Stop 路径上的完成门（见
+[跨会话记忆](/concepts/cross-session-memory)）不再接受一份代理 handoff 作为
+代码变更已完成的证明。对任何动了源码的会话，这个门都要求**真实的测试证据**：
+
+- 会话 diff 里改动过一个测试文件，**或者**
+- 针对当前变更有一次新鲜通过的 `forge verify` 记录在案。
+
+单独一份 `forge handoff` 快照并不能满足这个门 —— 它记录的是意图，而不是
+验证。如果两种证据都没有，这个门会**阻塞一次**，并附上一份修复清单：
+
+```bash
+forge verify                              # produce the test evidence
+forge handoff "<done>" --next "<next>"    # then snapshot the session
+```
+
+只改文档、只改配置以及其他非代码的会话不受影响 —— 只有当会话的 diff 真的
+动了代码时，测试证据的要求才会触发。
+
 ## UI 检查 —— `forge uicheck`
 
 确定性的 UI 检查，前三个视角不需要 LLM 也不需要截图：

mintlify/concepts/cross-session-memory.mdx

@@ -47,10 +47,16 @@ on the agent.
   allows (fail-open). `FORGE_STOPGATE=0` disables it.
 </Note>
 
+For sessions that changed code, the gate also requires **test evidence** — either a test
+file in the session's diff or a fresh passing `forge verify` against the current
+changes. A `forge handoff` snapshot alone no longer clears the code-change branch of the
+gate.
+
 The repair checklist points at the tools that finish the work:
 
 ```bash
-forge docs sync                      # sweep the diff for stale doc mentions
+forge verify                             # record the test evidence for code changes
+forge docs sync                          # sweep the diff for stale doc mentions
 forge handoff "<done>" --next "<next>"   # write the bounded session snapshot
 forge decide "<decision> — <reason>"     # record a choice so no session re-decides it
 ```

mintlify/concepts/verification-gates.mdx

@@ -29,6 +29,20 @@ forge verify --deep       # multi-lens consensus — several independent checks
   independent verification lenses, not just one.
 </Note>
 
+`forge verify --deep` reports a four-state `status`, not a binary pass/fail:
+
+- `PASS` — every lens agreed **and** the core `forge verify` tests status is also
+  `PASS`. Only this state counts as verified.
+- `FAIL` — at least one lens reported a real failure.
+- `INCOMPLETE` — a lens could not finish (timeout, crash, missing dependency). Nothing
+  was disproven, but nothing was proven either.
+- `NOT_CONFIGURED` — no lenses are wired up for this repo, so `--deep` had nothing to
+  check.
+
+The `PASS`-implies-base-`PASS` rule is deliberate: a green deep consensus can never
+outrun a red base run, so `INCOMPLETE` or `NOT_CONFIGURED` on the base test lens
+downgrades the deep result to match.
+
 ## The hallucinated-symbol flag — `forge atlas has`
 
 `forge atlas has <symbol>` is the hallucination check: if the model calls a symbol that
@@ -84,6 +98,28 @@ forge harden               # gitleaks pre-commit + sandbox settings
   commit time so partial or unverified work is caught before it lands.
 </Note>
 
+## Completion gate — test evidence required
+
+The Stop-path completion gate (see
+[Cross-session memory](/concepts/cross-session-memory)) no longer accepts an agent
+handoff as proof that code changes are done. For any session that touched source code,
+the gate requires **real test evidence**:
+
+- a test file changed in the session's diff, **or**
+- a fresh passing `forge verify` recorded against the current changes.
+
+A `forge handoff` snapshot on its own does not satisfy the gate — it records intent, not
+verification. If neither piece of evidence is present, the gate blocks once with a
+repair checklist:
+
+```bash
+forge verify                              # produce the test evidence
+forge handoff "<done>" --next "<next>"    # then snapshot the session
+```
+
+Doc-only, config-only, and other non-code sessions are unaffected — the test-evidence
+requirement fires only when the session's diff actually changes code.
+
 ## UI checks — `forge uicheck`
 
 Deterministic UI checks, no LLM and no screenshots for the first three lenses:

mintlify/hi/cli/quality.mdx

@@ -15,6 +15,19 @@ forge verify
 forge verify --deep       # multi-lens consensus (v0.19+)
 ```
 
+`forge verify --deep` सामान्य pass/fail के बजाय एक चार-अवस्था वाला `status` रिपोर्ट करता है:
+
+| Status           | अर्थ                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------ |
+| `PASS`           | हर lens सहमत हुआ **और** core `forge verify` tests status भी `PASS` है।                    |
+| `FAIL`           | कम-से-कम एक lens ने वास्तविक failure रिपोर्ट किया।                                            |
+| `INCOMPLETE`     | कोई lens पूरा नहीं हो सका (timeout, crash, missing dependency) — इसे unproven मानें।         |
+| `NOT_CONFIGURED` | इस repo के लिए कोई lenses wired नहीं हैं — असल में कुछ भी check नहीं हुआ।                       |
+
+केवल `PASS` को verified माना जाता है। `--deep` जानबूझकर consensus को `PASS` पर promote
+करने से मना कर देता है जब अंतर्निहित `forge verify` tests status `PASS` के अलावा कुछ भी हो, इसलिए
+एक हरा deep run हमेशा एक हरे base run का संकेत देता है।
+
 ## `forge scan`
 
 Skill-गेट — इंस्टॉल से पहले किसी skill या MCP सर्वर की injection / RCE / exfil के लिए जाँच करें।