@alucify/cli 0.7.1 → 0.7.3

package/dist/docs/help/mcp-server/tools/verify-plan.md

@@ -6,15 +6,15 @@ description: "How the verify_plan tool mechanically checks a plan's appgraph ref
 
 # Verifying a Plan
 
-The `verify_plan` tool checks a planning document against the appgraph to catch invented IDs, off-by-one drift, and silent omissions before the plan is presented or executed.
+The `verify_plan` tool checks a planning document against the appgraph to catch invented IDs and silent omissions before the plan is presented or executed, and surfaces advisory drift warnings for human review.
 
 ## What It Does
 
-Runs three deterministic checks against the plan text:
+Runs two hard checks (gate `valid`) and one advisory check (does not gate `valid`):
 
-1. **Invalid IDs** — Extracts every appgraph ID (`nv*`, `nl*`, `ni*`, `nr*`, `ns*`) from the plan and confirms each exists in the current appgraph. Catches hallucinations.
-2. **Name mismatches** — Compares the plan's description near each ID against the actual node's name and description using token overlap. Catches off-by-one drift where the plan cites the wrong ID for a described task.
-3. **Missing coverage** — Lists untested validations and in-progress components that need work but aren't referenced anywhere in the plan. Catches silent omissions.
+1. **Invalid IDs (hard fail)** — Extracts every appgraph ID (`nv*`, `nl*`, `ni*`, `nr*`, `ns*`) from the plan and confirms each exists in the current appgraph. Catches hallucinations.
+2. **Missing coverage (hard fail)** — Lists untested validations and in-progress components that need work but aren't referenced anywhere in the plan. Catches silent omissions.
+3. **Name mismatches (advisory)** — Compares the plan's description near each ID against the actual node's name and description using token overlap. Surfaced as warnings under `warnings.nameMismatches` because the heuristic false-positives on legitimate batch listings (e.g. compact ID enumerations where descriptive prose lives elsewhere in the plan). Reviewed by the agent, not enforced.
 
 No LLM calls — all checks are mechanical.
 
@@ -30,19 +30,10 @@ No LLM calls — all checks are mechanical.
 ```json
 {
   "valid": false,
-  "summary": "Found 44 IDs in plan | 11 INVALID (do not exist in appgraph) | 7 likely mismatched | 22 missing coverage",
+  "summary": "Found 44 IDs in plan | 11 INVALID (do not exist in appgraph) | 22 missing coverage | 7 drift warnings (advisory)",
   "invalidIds": [
     { "id": "nv00057", "nearbyText": "Task 5.1: TestAC_AgentAccountFieldSync (nv00057) ..." }
   ],
-  "nameMismatches": [
-    {
-      "id": "nv00042",
-      "actualName": "Orphaned quota entry is warned and excluded",
-      "actualDescription": "...",
-      "planContext": "Task 2.7: TestLoadState_Corrupted (nv00042) — test malformed JSON...",
-      "similarity": 0.04
-    }
-  ],
   "missingIds": [
     {
       "id": "nv00001",
@@ -52,13 +43,27 @@ No LLM calls — all checks are mechanical.
       "reason": "untested validation"
     }
   ],
-  "guidance": "Fix invalid IDs: these do not exist in the appgraph..."
+  "missingIdsTruncated": 0,
+  "warnings": {
+    "nameMismatches": [
+      {
+        "id": "nv00042",
+        "actualName": "Orphaned quota entry is warned and excluded",
+        "actualDescription": "...",
+        "planContext": "Task 2.7: TestLoadState_Corrupted (nv00042) — test malformed JSON...",
+        "similarity": 0.04
+      }
+    ]
+  },
+  "guidance": "Fix invalid IDs: these do not exist in the appgraph. Add coverage for missing IDs ... Review drift warnings (advisory, do not block) ..."
 }
 ```
 
+`valid` is `true` when both `invalidIds` and `missingIds` are empty, regardless of how many `warnings.nameMismatches` entries exist.
+
 ## How It's Used
 
-The `/alucify-plan` skill calls this tool as the final step before presenting a plan. If verification fails, the planning agent fixes the flagged issues and re-runs verification until `valid: true`.
+The `/alucify-plan` skill calls this tool as the final step before presenting a plan. If hard checks fail, the planning agent fixes the flagged issues and re-runs verification until `valid: true`. Drift warnings under `warnings.nameMismatches` are reviewed but do not block presentation.
 
 ## Example Workflow
 
@@ -66,17 +71,20 @@ The `/alucify-plan` skill calls this tool as the final step before presenting a
 1. Plan agent writes plan referencing nv00057-nv00067
 2. verify_plan returns invalidIds: ["nv00057", ...] because IDs only go up to nv00055
 3. Plan agent removes invented IDs, replaces with real ones from get_implementation_tasks
-4. verify_plan re-runs — this time nameMismatches flags nv00042 because the plan's
-   description ("TestLoadState_Corrupted") doesn't match nv00042's actual name
-   ("Orphaned quota entry warning")
-5. Plan agent corrects the ID mapping
-6. verify_plan re-runs and returns valid: true
+4. verify_plan re-runs and returns valid: true with 7 entries in warnings.nameMismatches
+   (most are batch ID listings — false positives)
+5. Plan agent reviews each warning. For one (nv00042), the plan's description
+   ("TestLoadState_Corrupted") doesn't match nv00042's actual name
+   ("Orphaned quota entry warning") — agent re-maps the task to the correct ID.
+   The other 6 are confirmed false positives (compact ID lists) and left alone.
+6. verify_plan re-runs (optional) — still valid: true, 6 advisory warnings remain
 7. Plan is presented to the user
 ```
 
 ## Notes
 
-- Name mismatches use a conservative similarity threshold — only obvious mismatches are flagged
-- The tool does not check the quality of the plan's tasks — only whether IDs are real and coverage is complete
-- `missingIds` is capped at 100 results to keep the response bounded
-- Safe to call repeatedly — verification is cheap and has no side effects
+- Drift warnings (`warnings.nameMismatches`) are advisory — they surface possible off-by-one errors but false-positive on legitimate batch ID listings, tables, and reference dumps where descriptive prose lives elsewhere. The agent reviews them; they do not block `valid: true`.
+- The similarity threshold is conservative (low bar) to catch obvious mismatches; tighter thresholds would miss real drift.
+- The tool does not check the quality of the plan's tasks — only whether IDs are real and coverage is complete.
+- `missingIds` is capped at 100 results to keep the response bounded.
+- Safe to call repeatedly — verification is cheap and has no side effects.