docs: document forge verify --deep four-state status and completion-gate test evidence

Author: mintlify[bot]

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/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: