nimai-mcp 0.3.6 → 0.3.8

package/data/FORGE-quickref.md

@@ -212,17 +212,23 @@ You are a Specification Quality Reviewer operating under the FORGE framework.
 Your job is to evaluate the draft spec below for spec quality only — not implementation correctness.
 Do NOT assess any code, code diffs, or implementation output.
 
-Evaluate each dimension with a binary PASS or FAIL:
-1. Binary acceptance criteria — are all sub-task ACs measurable and unambiguous?
-2. Scope coherence — are in-scope/out-of-scope boundaries clear and non-contradictory?
-3. Constraint sufficiency — do Must/Must-Not/Prefer/Escalate constraints cover key risks?
-4. Decomposition realism — can each sub-task be done within 2 hours by a skilled agent?
-5. Start-without-clarification viability — can an agent begin immediately without asking for more info?
-
-Always end your response with a JSON verdict block:
+Evaluate each dimension. Cite evidence for every verdict — a verdict without citation is treated as NO_GO.
+Classify each issue as HARD_FAIL, SOFT_FAIL, or NOTE. passed: true requires zero HARD_FAILs.
+
+1. Binary acceptance criteria — are all sub-task ACs measurable and unambiguous? Pre-checked [x] ACs are always invalid.
+2. Scope coherence — are in-scope/out-of-scope boundaries clear and non-contradictory? Terminology mismatches between conceptual and persisted representations are a HARD_FAIL.
+3. Constraint sufficiency — do Must/Must-Not/Prefer/Escalate constraints cover the key risks?
+4. Decomposition realism — can each sub-task be done within 2 hours? Sub-task dependencies must be explicit.
+5. Start-without-clarification viability — can an agent begin immediately with the context provided?
+6. Internal consistency — are terms, names, and concepts used consistently throughout?
+7. Mechanism lock — does every core flow commit to exactly ONE implementation path? Any "e.g./or/could/might/such as" in Deliverable, Scope, Constraints, or Tasks is a HARD_FAIL.
+8. Convergence declaration — does the spec include a Spec Convergence section with open_questions: 0 and ambiguities_remaining: 0? Absent, non-zero, or ready_for_build: no is a HARD_FAIL.
+9. Adversarial gap scan — does the spec include a substantively filled Edge Cases and Failure Modes section? Steelman as a builder following it exactly: what failure modes are unaddressed? Absent or placeholder-only is a HARD_FAIL for medium/high risk specs.
+
+Always end your response with:
 ## Verdict
 ```json
-{"passed": <true|false>, "issues": ["<issue>", ...]}
+{"passed": <true|false>, "schema_version": "2", "issues": [{"dimension": "<name>", "severity": "<HARD_FAIL|SOFT_FAIL|NOTE>", "detail": "<cited evidence>"}]}
 ```
 
 Draft spec: [PASTE DRAFT SPEC HERE]
@@ -306,6 +312,7 @@ PASS → done  |  FAIL → revise or escalate
 - [ ] Spec red-teamed against Failure Mode Taxonomy
 - [ ] Planner execution plan will be saved as artifact
 - [ ] Living Specification log set up (multi-session)
+- [ ] Spec Convergence section filled — `open_questions: 0`, `ambiguities_remaining: 0`, `ready_for_build: yes`
 
 ---
 

package/data/FORGE-spec-template.md

@@ -91,6 +91,26 @@ The project is complete when ALL of the following are true:
 
 ---
 
+## 1.5 Mechanism Decision
+*One block per core architectural or algorithmic choice. If no core mechanism applies, write "N/A" and justify.*
+*A builder must be able to start coding without choosing missing architecture. If any mechanism is undecided, resolve it here first.*
+
+---
+
+**Decision: [short name, e.g., "Primary parsing method"]**
+
+```
+Chosen approach: _______________________________________________
+
+Rejected alternatives: _________________________________________
+
+Why rejected: __________________________________________________
+
+Impact on ACs: _________________________________________________
+```
+
+---
+
 ## 2. Intent Layer — The Compass
 
 ### 2.1 Agent Deployment Purpose
@@ -372,6 +392,37 @@ Acceptance criteria: _____________________________________
 
 ---
 
+## 8.5 Edge Cases and Failure Modes
+> Required for medium/high risk specs. Red-team the spec before builder handoff.
+> For each scenario, document what the spec says the builder must do. A blank list is a hard stop.
+
+**FORGE failure mode coverage:**
+- Scope Creep — which Must-Not explicitly prevents it: `_______________`
+- Hallucinated Completion — which AC is hardest to fake: `_______________`
+- Intent Drift — which decision will the builder most likely get wrong: `_______________`
+- Context Collapse — what context is load-bearing and must not be dropped: `_______________`
+- Runaway Cost — what resource cap prevents unbounded execution: `_______________`
+- Overconfident Output — what requires uncertainty reporting: `_______________`
+
+**Domain-specific edge cases:**
+- `_______________`
+- `_______________`
+
+---
+
+## 9. Spec Convergence
+> Fill before handing to a builder. A non-zero count or "no" is a hard stop.
+> Every [NEEDS HUMAN INPUT] flag from spec drafting must be resolved before this section is filled.
+
+```
+open_questions: 0
+ambiguities_remaining: 0
+ready_for_build: yes
+convergence_notes: _______________________________________________
+```
+
+---
+
 *FORGE Spec Template v1.0 — companion to the FORGE system. A blank field is an unresolved decision.*
 *System docs: Quick Reference · Canonical Framework · Spec Template (this doc)*
 

package/dist/tools/spec-review.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec-review.d.ts","sourceRoot":"","sources":["../../src/tools/spec-review.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wBAAsB,cAAc,CAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,GAC1C,OAAO,CAAC,qBAAqB,CAAC,CAgChC"}
+{"version":3,"file":"spec-review.d.ts","sourceRoot":"","sources":["../../src/tools/spec-review.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wBAAsB,cAAc,CAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,GAC1C,OAAO,CAAC,qBAAqB,CAAC,CAqDhC"}

package/dist/tools/spec-review.js

@@ -53,16 +53,37 @@ async function toolSpecReview(input) {
         'The spec-quality review must be done by an independent reviewer —',
         'NOT the agent that created or edited the spec.',
         '',
-        'Steps:',
+        '── STEP 1: Send to independent reviewer ──────────────────────────',
         '1. Copy the specReviewerPrompt string from this response.',
-        '2. Open a FRESH SESSION with a different model or agent (e.g. paste into Claude, a new Codex thread, or any LLM).',
-        '3. Paste the prompt and let the independent reviewer evaluate the spec.',
+        '2. Open a FRESH SESSION with a different model or agent',
+        '   (e.g. paste into Claude, a new Codex thread, or any LLM).',
+        '3. Paste the prompt and let the reviewer evaluate the spec.',
         '4. The reviewer will end their response with a JSON verdict block:',
         '   {"passed": true/false, "schema_version": "2", "issues": [...]}',
         '',
-        'Return the verdict here when done:',
-        '  • passed: true  → spec is approved, proceed to build',
-        '  • passed: false → share the issues list, fix the spec, re-run nimai_validate, then call nimai_spec_review again',
+        '── STEP 2: Return the verdict ────────────────────────────────────',
+        'Bring the full verdict back to THIS session.',
+        '',
+        '  If passed: true',
+        '  → The spec is approved. Proceed to implementation.',
+        '',
+        '  If passed: false',
+        '  → Do NOT re-run nimai_spec (that would discard all spec work).',
+        `  → Give the builder this message (fill in the verdict):`,
+        '',
+        `  ┌─ BUILDER FIX BRIEF ──────────────────────────────────────────`,
+        `  │ The independent spec review found issues in: ${specPath}`,
+        `  │`,
+        `  │ Fix each HARD_FAIL and SOFT_FAIL in the verdict below by`,
+        `  │ editing the spec directly. Do not regenerate from scratch.`,
+        `  │`,
+        `  │ [PASTE VERDICT HERE]`,
+        `  │`,
+        `  │ After fixing:`,
+        `  │ 1. Run nimai_validate — must return passed: true`,
+        `  │ 2. Run nimai_spec_review — get new reviewer_instructions`,
+        `  │ 3. Send to an independent reviewer again (do not self-review)`,
+        `  └──────────────────────────────────────────────────────────────`,
     ].join('\n');
     return { specReviewerPrompt, reviewer_instructions };
 }

package/dist/tools/spec-review.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec-review.js","sourceRoot":"","sources":["../../src/tools/spec-review.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMA,wCAkCC;AAxCD,uCAAyB;AACzB,2CAA6B;AAC7B,2CAA2C;AAIpC,KAAK,UAAU,cAAc,CAClC,KAA2C;IAE3C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,WAAmB,CAAC;IACxB,IAAI,CAAC;QACH,WAAW,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,wBAAwB,QAAQ,MAAO,GAA6B,CAAC,OAAO,EAAE,CAC/E,CAAC;IACJ,CAAC;IAED,MAAM,kBAAkB,GAAG,IAAA,0BAAa,EAAC,WAAW,CAAC,CAAC;IAEtD,MAAM,qBAAqB,GAAG;QAC5B,iCAAiC;QACjC,EAAE;QACF,mEAAmE;QACnE,gDAAgD;QAChD,EAAE;QACF,QAAQ;QACR,2DAA2D;QAC3D,mHAAmH;QACnH,yEAAyE;QACzE,oEAAoE;QACpE,mEAAmE;QACnE,EAAE;QACF,oCAAoC;QACpC,wDAAwD;QACxD,mHAAmH;KACpH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,CAAC;AACvD,CAAC"}
+{"version":3,"file":"spec-review.js","sourceRoot":"","sources":["../../src/tools/spec-review.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMA,wCAuDC;AA7DD,uCAAyB;AACzB,2CAA6B;AAC7B,2CAA2C;AAIpC,KAAK,UAAU,cAAc,CAClC,KAA2C;IAE3C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,WAAmB,CAAC;IACxB,IAAI,CAAC;QACH,WAAW,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,wBAAwB,QAAQ,MAAO,GAA6B,CAAC,OAAO,EAAE,CAC/E,CAAC;IACJ,CAAC;IAED,MAAM,kBAAkB,GAAG,IAAA,0BAAa,EAAC,WAAW,CAAC,CAAC;IAEtD,MAAM,qBAAqB,GAAG;QAC5B,iCAAiC;QACjC,EAAE;QACF,mEAAmE;QACnE,gDAAgD;QAChD,EAAE;QACF,oEAAoE;QACpE,2DAA2D;QAC3D,yDAAyD;QACzD,8DAA8D;QAC9D,6DAA6D;QAC7D,oEAAoE;QACpE,mEAAmE;QACnE,EAAE;QACF,oEAAoE;QACpE,8CAA8C;QAC9C,EAAE;QACF,mBAAmB;QACnB,sDAAsD;QACtD,EAAE;QACF,oBAAoB;QACpB,kEAAkE;QAClE,0DAA0D;QAC1D,EAAE;QACF,mEAAmE;QACnE,oDAAoD,QAAQ,EAAE;QAC9D,KAAK;QACL,8DAA8D;QAC9D,gEAAgE;QAChE,KAAK;QACL,0BAA0B;QAC1B,KAAK;QACL,mBAAmB;QACnB,sDAAsD;QACtD,8DAA8D;QAC9D,mEAAmE;QACnE,mEAAmE;KACpE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,CAAC;AACvD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nimai-mcp",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Nimai MCP server — exposes nimai_spec, nimai_review, nimai_validate, nimai_new as tools. No internal LLM calls.",
   "keywords": [
     "nimai",
@@ -36,7 +36,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.8",
-    "nimai-core": "0.3.6"
+    "nimai-core": "0.3.8"
   },
   "scripts": {
     "build": "tsc",