nimai-core 0.1.1 → 0.2.0

package/dist/clarification.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Rule-based clarification heuristics for nimai_spec.
+ *
+ * These are pure functions — no IO, no LLM calls.
+ * Trigger `clarifications_needed` when any heuristic fires.
+ */
+export interface ClarificationResult {
+    needed: boolean;
+    reasons: string[];
+    questions: string[];
+}
+/**
+ * Evaluate whether a spec request needs clarification before drafting.
+ *
+ * Heuristics (any one firing triggers clarification):
+ * 1. Request is under 10 words
+ * 2. Zero repo files matched by context extractor
+ * 3. No domain nouns or action verbs detected
+ * 4. Conflicting stack hints (two competing tech choices in same category)
+ */
+export declare function detectClarifications(request: string, contextFileCount: number): ClarificationResult;
+//# sourceMappingURL=clarification.d.ts.map

package/dist/clarification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarification.d.ts","sourceRoot":"","sources":["../src/clarification.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuEH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,MAAM,GACvB,mBAAmB,CA+BrB"}

package/dist/clarification.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Rule-based clarification heuristics for nimai_spec.
+ *
+ * These are pure functions — no IO, no LLM calls.
+ * Trigger `clarifications_needed` when any heuristic fires.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectClarifications = detectClarifications;
+// ─── Domain noun / action vocab ───────────────────────────────────────────────
+/**
+ * Minimum set of technical domain nouns and action verbs that indicate the
+ * request describes a real engineering task. If the request contains none of
+ * these, it is likely too vague to spec reliably.
+ */
+const DOMAIN_TOKENS = new Set([
+    // Action verbs
+    'add', 'build', 'create', 'implement', 'fix', 'refactor', 'update', 'migrate',
+    'design', 'integrate', 'deploy', 'remove', 'generate', 'optimize', 'extend',
+    'replace', 'extract', 'expose', 'wire', 'scaffold', 'test', 'benchmark',
+    // Technical nouns
+    'api', 'service', 'component', 'model', 'module', 'database', 'endpoint',
+    'interface', 'schema', 'type', 'function', 'class', 'route', 'handler',
+    'middleware', 'auth', 'token', 'config', 'cli', 'ui', 'hook', 'store',
+    'query', 'mutation', 'event', 'queue', 'cache', 'index', 'migration',
+    'server', 'client', 'backend', 'frontend', 'test', 'spec', 'pipeline',
+    'workflow', 'adapter', 'plugin', 'sdk', 'contract', 'validator', 'parser',
+]);
+/**
+ * Returns true if the request contains at least one recognizable domain token.
+ */
+function hasDomainNoun(request) {
+    const words = request.toLowerCase().match(/\b[a-z]+\b/g) ?? [];
+    return words.some(w => DOMAIN_TOKENS.has(w));
+}
+// ─── Conflicting stack detection ──────────────────────────────────────────────
+/** Groups of mutually-competing technology choices. Two items from the same group = conflict. */
+const STACK_GROUPS = [
+    // Programming languages — any two in the same request signals ambiguous stack
+    [
+        'python', 'ruby', 'java', 'golang', 'rust', 'kotlin', 'swift', 'scala',
+        'php', 'elixir', 'csharp', 'typescript', 'javascript',
+    ],
+    // JS UI frameworks
+    ['react', 'vue', 'angular', 'svelte'],
+    // CSS frameworks
+    ['tailwind', 'bootstrap'],
+    // Relational databases
+    ['postgresql', 'postgres', 'mysql', 'sqlite'],
+    // NoSQL databases
+    ['mongodb', 'dynamodb', 'firestore', 'cassandra'],
+    // JS test frameworks
+    ['jest', 'vitest', 'jasmine'],
+];
+/**
+ * Returns true if the request mentions ≥2 items from the same competing stack group,
+ * indicating an ambiguous or conflicting technology choice.
+ */
+function hasConflictingStack(request) {
+    const lower = request.toLowerCase();
+    for (const group of STACK_GROUPS) {
+        const hits = group.filter(tech => {
+            // Match as whole word or compound (e.g. "typescript", "vue.js")
+            const pattern = new RegExp(`\\b${tech.replace(/[-.]/g, '[-.\\s]?')}\\b`, 'i');
+            return pattern.test(lower);
+        });
+        if (hits.length >= 2)
+            return true;
+    }
+    return false;
+}
+/**
+ * Evaluate whether a spec request needs clarification before drafting.
+ *
+ * Heuristics (any one firing triggers clarification):
+ * 1. Request is under 10 words
+ * 2. Zero repo files matched by context extractor
+ * 3. No domain nouns or action verbs detected
+ * 4. Conflicting stack hints (two competing tech choices in same category)
+ */
+function detectClarifications(request, contextFileCount) {
+    const reasons = [];
+    const wordCount = request.trim().split(/\s+/).length;
+    if (wordCount < 10) {
+        reasons.push(`request is too short (${wordCount} words — add more context)`);
+    }
+    if (contextFileCount === 0) {
+        reasons.push('no relevant repo files matched — is the repo path correct, or is this a new project?');
+    }
+    if (!hasDomainNoun(request)) {
+        reasons.push('no recognizable domain nouns or action verbs found — describe what should be built or changed');
+    }
+    if (hasConflictingStack(request)) {
+        reasons.push('conflicting technology stack hints detected — clarify which stack applies or separate into distinct tasks');
+    }
+    const needed = reasons.length > 0;
+    const questions = needed
+        ? [
+            'What is the primary goal or outcome you want to achieve?',
+            'Which specific files, components, or systems should be modified?',
+            'Are there constraints, dependencies, or requirements we should be aware of?',
+        ]
+        : [];
+    return { needed, reasons, questions };
+}
+//# sourceMappingURL=clarification.js.map

package/dist/clarification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarification.js","sourceRoot":"","sources":["../src/clarification.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAsFH,oDAkCC;AAtHD,iFAAiF;AAEjF;;;;GAIG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,eAAe;IACf,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS;IAC7E,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ;IAC3E,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW;IACvE,kBAAkB;IAClB,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU;IACxE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS;IACtE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO;IACrE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW;IACpE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU;IACrE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ;CAC1E,CAAC,CAAC;AAEH;;GAEG;AACH,SAAS,aAAa,CAAC,OAAe;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;IAC/D,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,iFAAiF;AAEjF,iGAAiG;AACjG,MAAM,YAAY,GAAe;IAC/B,8EAA8E;IAC9E;QACE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO;QACtE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY;KACtD;IACD,mBAAmB;IACnB,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC;IACrC,iBAAiB;IACjB,CAAC,UAAU,EAAE,WAAW,CAAC;IACzB,uBAAuB;IACvB,CAAC,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC;IAC7C,kBAAkB;IAClB,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,CAAC;IACjD,qBAAqB;IACrB,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC;CAC9B,CAAC;AAEF;;;GAGG;AACH,SAAS,mBAAmB,CAAC,OAAe;IAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;YAC/B,gEAAgE;YAChE,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC9E,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACpC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAUD;;;;;;;;GAQG;AACH,SAAgB,oBAAoB,CAClC,OAAe,EACf,gBAAwB;IAExB,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;IACrD,IAAI,SAAS,GAAG,EAAE,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,yBAAyB,SAAS,4BAA4B,CAAC,CAAC;IAC/E,CAAC;IAED,IAAI,gBAAgB,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,sFAAsF,CAAC,CAAC;IACvG,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,IAAI,CAAC,+FAA+F,CAAC,CAAC;IAChH,CAAC;IAED,IAAI,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,OAAO,CAAC,IAAI,CAAC,2GAA2G,CAAC,CAAC;IAC5H,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAElC,MAAM,SAAS,GAAa,MAAM;QAChC,CAAC,CAAC;YACE,0DAA0D;YAC1D,kEAAkE;YAClE,6EAA6E;SAC9E;QACH,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AACxC,CAAC"}

package/dist/context.js

@@ -74,9 +74,9 @@ function walkDir(rootPath, currentPath, results, keywords) {
             catch {
                 continue;
             }
-            const relevance = scoreRelevance(entry.name, content, keywords);
+            const relPath = path.relative(rootPath, fullPath);
+            const relevance = scoreRelevance(entry.name, content, keywords, relPath);
             if (relevance > 0) {
-                const relPath = path.relative(rootPath, fullPath);
                 results.push({
                     file: relPath,
                     snippet: content.slice(0, MAX_SNIPPET_CHARS),
@@ -86,11 +86,31 @@ function walkDir(rootPath, currentPath, results, keywords) {
         }
     }
 }
-function scoreRelevance(filename, content, keywords) {
+// Source dirs score higher than docs/examples/schemas
+const SOURCE_DIR_PATTERNS = ['src/', 'lib/', 'app/', 'server/', 'api/'];
+const DOCS_DIR_PATTERNS = ['docs/', 'examples/', 'schemas/'];
+function scoreRelevance(filename, content, keywords, relPath) {
     if (keywords.length === 0)
         return 1;
     const lower = (filename + ' ' + content).toLowerCase();
-    return keywords.filter(k => lower.includes(k)).length;
+    const keywordScore = keywords.filter(k => lower.includes(k)).length;
+    if (keywordScore === 0)
+        return 0;
+    // Filename boost: if the filename itself matches a keyword, it's likely the most relevant file
+    const filenameLower = filename.toLowerCase().replace(/\.[^.]+$/, '');
+    const filenameBoost = keywords.some(k => filenameLower.includes(k)) ? 2 : 0;
+    // Path boost: source files score higher than docs/examples
+    let pathBoost = 0;
+    if (relPath) {
+        const rel = relPath.toLowerCase();
+        if (SOURCE_DIR_PATTERNS.some(p => rel.startsWith(p)))
+            pathBoost = 1;
+        if (DOCS_DIR_PATTERNS.some(p => rel.startsWith(p)))
+            pathBoost = -1;
+    }
+    // Nimai spec boost: files containing the <!-- nimai-spec --> marker are prioritised
+    const nimaiBoost = content.includes('<!-- nimai-spec -->') ? 2 : 0;
+    return keywordScore + filenameBoost + pathBoost + nimaiBoost;
 }
 function tokenize(request) {
     return request

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from './template';
 export * from './lint';
 export * from './context';
 export * from './prompts';
+export * from './clarification';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -19,4 +19,5 @@ __exportStar(require("./template"), exports);
 __exportStar(require("./lint"), exports);
 __exportStar(require("./context"), exports);
 __exportStar(require("./prompts"), exports);
+__exportStar(require("./clarification"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,4CAA0B;AAC1B,4CAA0B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,4CAA0B;AAC1B,4CAA0B;AAC1B,kDAAgC"}

package/dist/lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAiB,MAAM,SAAS,CAAC;AAyCnD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAQtD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CA+BxD"}
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAiB,MAAM,SAAS,CAAC;AA8DnD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAQtD;AAsBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CA2CxD"}

package/dist/lint.js

@@ -50,12 +50,16 @@ const REQUIRED_SECTIONS = [
     'governance & validation',
 ];
 // Advisory: architecture quality signals (anti-spaghetti rules)
-// Each rule looks for at least one keyword/heading indicating the concept is addressed
+// Each rule looks for at least one keyword/heading indicating the concept is addressed.
+// Rules marked hardFailTiers become hard failures (not advisory) when the spec's risk tier
+// matches AND (if codingOnly=true) the spec is a coding/tooling/server spec.
 const ADVISORY_RULES = [
     {
         type: 'missing_module_boundary',
-        keywords: ['module boundary', 'package boundary', 'layer boundary', 'separation of concerns', 'packages/core', 'packages/mcp', 'packages/cli'],
-        message: 'No module boundary definition found — consider documenting package/layer boundaries',
+        keywords: ['module boundary', 'package boundary', 'layer boundary', 'separation of concerns', 'packages/core', 'packages/mcp', 'packages/cli', 'app/models', 'app/state', 'app/db'],
+        message: 'No module boundary definition found — document package/layer boundaries and which layers may not import each other',
+        hardFailTiers: ['medium', 'high'],
+        codingOnly: true,
     },
     {
         type: 'missing_interface_contract',
@@ -65,12 +69,22 @@ const ADVISORY_RULES = [
     {
         type: 'missing_non_goals',
         keywords: ['non-goal', 'non-goals', 'must-not', 'scope — out', 'out of scope', 'deferred', 'excluded'],
-        message: 'No non-goals or out-of-scope section found — consider documenting what this spec explicitly excludes',
+        message: 'No non-goals or out-of-scope section found — document what this spec explicitly excludes',
+        hardFailTiers: ['medium', 'high'],
     },
     {
         type: 'missing_change_surface',
         keywords: ['change surface', 'breaking change', 'migration', 'backward compat', 'semver', 'versioning', 'deprecat'],
-        message: 'No change surface documentation found — consider documenting compatibility expectations',
+        message: 'No change surface documentation found — document compatibility expectations and what this spec must not break',
+        hardFailTiers: ['medium', 'high'],
+    },
+    {
+        type: 'missing_dependency_direction',
+        keywords: ['dependency direction', 'may not import', 'must not import', 'import from', 'no cross-layer', 'dependency rule', 'import rule'],
+        message: 'No dependency direction rules found — document which modules/layers may import which (prevents circular and cross-layer dependencies)',
+        hardFailTiers: ['medium', 'high'],
+        codingOnly: true,
+        skipAdvisoryForTiers: ['low', 'unknown'],
     },
 ];
 function lintSpec(filePath) {
@@ -83,6 +97,25 @@ function lintSpec(filePath) {
     }
     return lintContent(content);
 }
+/** Detect risk tier from checked checkbox in spec content */
+function detectRiskTier(content) {
+    if (/\[x\]\s*high/i.test(content))
+        return 'high';
+    if (/\[x\]\s*medium/i.test(content))
+        return 'medium';
+    if (/\[x\]\s*low/i.test(content))
+        return 'low';
+    return 'unknown';
+}
+/** Detect if this is a coding/tooling/server spec (vs docs/research/strategy) */
+function isCodingSpec(content) {
+    const lower = content.toLowerCase();
+    return (lower.includes('if coding') ||
+        lower.includes('language / framework') ||
+        lower.includes('language/framework') ||
+        lower.includes('test coverage expectation') ||
+        lower.includes('performance targets'));
+}
 function lintContent(content) {
     const issues = [];
     const lines = content.split('\n');
@@ -102,10 +135,20 @@ function lintContent(content) {
             issues.push(issue(0, 'missing_section', `Required section missing: "${section}"`));
         }
     }
+    const riskTier = detectRiskTier(content);
+    const coding = isCodingSpec(content);
     for (const rule of ADVISORY_RULES) {
         const found = rule.keywords.some(kw => lower.includes(kw.toLowerCase()));
         if (!found) {
-            issues.push(advisoryIssue(0, rule.type, rule.message));
+            const shouldHardFail = rule.hardFailTiers !== undefined &&
+                rule.hardFailTiers.includes(riskTier) &&
+                (!rule.codingOnly || coding);
+            if (shouldHardFail) {
+                issues.push(issue(0, rule.type, `${rule.message} [required for ${riskTier}-risk${rule.codingOnly ? ' coding' : ''} specs]`));
+            }
+            else if (!rule.skipAdvisoryForTiers?.includes(riskTier)) {
+                issues.push(advisoryIssue(0, rule.type, rule.message));
+            }
         }
     }
     return issues;

package/dist/lint.js.map

@@ -1 +1 @@
-{"version":3,"file":"lint.js","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"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"}

package/dist/prompts.d.ts

@@ -8,6 +8,19 @@
  * Returns the populated prompt ready to hand to a host model.
  */
 export declare function buildPrompt1(request: string, contextSummary: string): string;
+/**
+ * FORGE Prompt 1.5 — Spec-Quality Reviewer.
+ * Returns a prompt for a reviewing LLM to evaluate whether a draft spec is
+ * executable by an agent without requiring clarifying questions.
+ *
+ * The reviewing LLM MUST end its response with a machine-parseable JSON verdict block:
+ *   ## Verdict
+ *   ```json
+ *   {"passed": true, "issues": []}
+ *   ```
+ * The host agent parses this block to drive the spec-review loop.
+ */
+export declare function buildPrompt15(specContent: string): string;
 /**
  * FORGE Prompt 2 — Reviewer / Validator Prompt Generator (from FORGE-quickref.md).
  * Returns the populated reviewer prompt derived from an approved spec.

package/dist/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CA0B5E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAgBxD"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CA0B5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAuCzD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAgBxD"}

package/dist/prompts.js

@@ -6,6 +6,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildPrompt1 = buildPrompt1;
+exports.buildPrompt15 = buildPrompt15;
 exports.buildPrompt2 = buildPrompt2;
 /**
  * FORGE Prompt 1 — Self-Spec Agent (from FORGE-quickref.md).
@@ -38,6 +39,58 @@ ${contextSummary || '(no repo context extracted)'}
 
 Loose request: ${request}`;
 }
+/**
+ * FORGE Prompt 1.5 — Spec-Quality Reviewer.
+ * Returns a prompt for a reviewing LLM to evaluate whether a draft spec is
+ * executable by an agent without requiring clarifying questions.
+ *
+ * The reviewing LLM MUST end its response with a machine-parseable JSON verdict block:
+ *   ## Verdict
+ *   ```json
+ *   {"passed": true, "issues": []}
+ *   ```
+ * The host agent parses this block to drive the spec-review loop.
+ */
+function buildPrompt15(specContent) {
+    return `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.
+
+## What to check
+
+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 and out-of-scope boundaries clearly stated and non-contradictory?
+3. **Constraint sufficiency** — do Must / Must-Not / Prefer / Escalate constraints cover the key risks?
+4. **Decomposition realism** — can each sub-task be completed within the stated 2-hour limit by a skilled agent?
+5. **Start-without-clarification viability** — can an agent begin immediately with the context provided, without asking the human for more information?
+
+## Output format
+
+For each check, write: **[PASS]** or **[FAIL]** followed by a one-sentence rationale.
+
+Then write a consolidated summary listing all failing dimensions and their remediation guidance.
+
+Note: implementation correctness is explicitly out of scope for this review.
+
+## Important
+
+Always end your response with the following verdict block as the **final section**, regardless of pass/fail outcome.
+The host agent parses this block to drive the loop — if it is absent or malformed, the host will treat the result as ambiguous and escalate to the human.
+
+## Verdict
+\`\`\`json
+{"passed": true, "issues": []}
+\`\`\`
+
+---
+
+## Draft spec to review
+
+${specContent}`;
+}
 /**
  * FORGE Prompt 2 — Reviewer / Validator Prompt Generator (from FORGE-quickref.md).
  * Returns the populated reviewer prompt derived from an approved spec.

package/dist/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAMH,oCA0BC;AAMD,oCAgBC;AApDD;;;GAGG;AACH,SAAgB,YAAY,CAAC,OAAe,EAAE,cAAsB;IAClE,OAAO;;;;;;;;;;;;;;;;;;;;;EAqBP,cAAc,IAAI,6BAA6B;;;iBAGhC,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,WAAmB;IAC9C,OAAO;;;;;;;;;;;;;;EAcP,WAAW,EAAE,CAAC;AAChB,CAAC"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAMH,oCA0BC;AAcD,sCAuCC;AAMD,oCAgBC;AAzGD;;;GAGG;AACH,SAAgB,YAAY,CAAC,OAAe,EAAE,cAAsB;IAClE,OAAO;;;;;;;;;;;;;;;;;;;;;EAqBP,cAAc,IAAI,6BAA6B;;;iBAGhC,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,aAAa,CAAC,WAAmB;IAC/C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqCP,WAAW,EAAE,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,WAAmB;IAC9C,OAAO;;;;;;;;;;;;;;EAcP,WAAW,EAAE,CAAC;AAChB,CAAC"}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type LintIssueType = 'blank_field' | 'needs_human_input' | 'missing_section' | 'missing_module_boundary' | 'missing_interface_contract' | 'missing_non_goals' | 'missing_change_surface';
+export type LintIssueType = 'blank_field' | 'needs_human_input' | 'missing_section' | 'missing_module_boundary' | 'missing_interface_contract' | 'missing_non_goals' | 'missing_change_surface' | 'missing_dependency_direction';
 export interface LintIssue {
     line: number;
     type: LintIssueType;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,mBAAmB,GACnB,iBAAiB,GACjB,yBAAyB,GACzB,4BAA4B,GAC5B,mBAAmB,GACnB,wBAAwB,CAAC;AAE7B,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,mBAAmB,GACnB,iBAAiB,GACjB,yBAAyB,GACzB,4BAA4B,GAC5B,mBAAmB,GACnB,wBAAwB,GACxB,8BAA8B,CAAC;AAEnC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nimai-core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Nimai core library — template loading, lint engine, context extraction. No LLM dependencies.",
   "keywords": [
     "nimai",