@asobacloud/nehanda 0.8.0 → 0.9.1

package/lib/orchestrate.mjs

@@ -10,6 +10,7 @@ import { evaluatePermission } from './permissions.mjs'
 import { executeBuiltinTool, anthropicToolDefinitions, openAICompatToolDefinitions, LOCAL_CORE_TOOLS, EXPLORE_ONLY_TOOLS, dynamicTools, getMcpToolDefinitions } from './tools.mjs'
 import { streamOpenAIChatCompletion, isAbortError } from './openaiCompat.mjs'
 import { withTransaction } from './store.mjs'
+import { upsertSummary } from './store.mjs'
 import { getPhase, setPhase, canTransition } from './workflow.mjs'
 import { buildJevSystem2Messages } from './compact.mjs'
 
@@ -200,6 +201,14 @@ RULES FOR PLAN STEPS:
 Do NOT use any tools. Write the plan only.`
 }
 
+function buildCreateTestUserMessage(planContent) {
+  return `Plan approved. Per TDD (AGENTS.md Phase 4), create or update behavioral tests now BEFORE modifying production code.
+
+${planContent}
+
+Write the behavioral test and run it using Bash to confirm it is demonstrably RED (failing for the diagnosed reason). End with "Tests failed: <reason>".`
+}
+
 function buildImplementUserMessage(planContent) {
   return `Approved plan:
 
@@ -250,6 +259,10 @@ export function buildSystemPrompt(cwd, provider, model, phase, onaInstructions,
   const builder = PHASE_SYSTEM[phase] || PHASE_SYSTEM.default
   let prompt = builder(cwd, provider, model, date, os, shell, onaInstructions)
 
+  // #22: Explicit grounded facts prevent reasoning models from spending tokens
+  // debating their own awareness of date, cwd, or environment.
+  prompt += `\n\n[GROUNDED FACTS]\nDate: ${date}\nWorking directory: ${cwd}\nPlatform: ${os} | Shell: ${shell}`
+
   // Inject intent-shaped task context preamble for idle/explore/default phases.
   // Not injected in implement/test/planning — those phases use generated template
   // messages that carry no real user intent signal.
@@ -378,18 +391,21 @@ async function toolsForProvider(provider, settings, nativeToolSupport = true) {
 
 const ollamaCapabilityCache = new Map()
 
-async function detectOllamaToolSupport(baseUrl, modelName) {
+async function detectOllamaToolSupport(baseUrl, modelName, signal) {
   const key = `${baseUrl}::${modelName}`
   if (ollamaCapabilityCache.has(key)) return ollamaCapabilityCache.get(key)
 
   let result = true
   try {
     const apiBase = baseUrl.replace(/\/v1\/?$/, '').replace(/\/+$/, '')
+    // #22: compose rt.signal with the 3 s timeout so Esc cancels the probe immediately
+    const timeoutSignal = AbortSignal.timeout(3000)
+    const fetchSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal
     const resp = await fetch(`${apiBase}/api/show`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ name: modelName }),
-      signal: AbortSignal.timeout(3000)
+      signal: fetchSignal,
     })
     if (!resp.ok) { result = true }
     else {
@@ -400,7 +416,9 @@ async function detectOllamaToolSupport(baseUrl, modelName) {
         data.capabilities?.includes('tools')
       )
     }
-  } catch {
+  } catch (e) {
+    // #22: re-throw user aborts — don't swallow as "assume native"
+    if (e?.name === 'AbortError') throw e
     result = true
   }
 
@@ -437,7 +455,7 @@ function rethrowIfAborted(e) {
 
 async function askHuman(io, q) {
   if (!process.stdin.isTTY) return true
-  if (io?.ask) return (await io.ask(q)).trim().toLowerCase().startsWith('y')
+  if (io?.ask) { const ans = await io.ask(q); return ans != null && ans.trim().toLowerCase().startsWith('y') }
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
   return new Promise(resolve => {
     rl.question(q, ans => { rl.close(); resolve(/^y(es)?$/i.test(String(ans || '').trim())) })
@@ -714,29 +732,49 @@ async function exploreGateAnthropic(db, rt, io, client, userRequest) {
   io.println(`✓ Exploration complete. Summarising ${filesRead.length} file(s)...`)
 
   const summaries = await summarizeFilesAnthropicForTask(client, rt, filesRead, userRequest, io)
+  // #11: persist summaries so a failed planning turn can be retried without re-exploration.
+  upsertSummary(db, rt.conversationId, JSON.stringify(summaries))
   appendEntry(db, rt.sessionId, 'user', makeUserPayload(buildPlanningUserMessage(summaries, userRequest)))
   setPhase(db, rt.conversationId, 'planning', 'explore_complete')
   io.println('✓ Summarisation complete. Entering planning phase.')
   return true
 }
 
-async function exploreGateOpenAICompat(db, rt, io, provider, baseUrl, apiKey, userRequest) {
+export async function exploreGateOpenAICompat(db, rt, io, provider, baseUrl, apiKey, userRequest) {
   const filesRead = extractFilesRead(db, rt.sessionId)
   io.println(`✓ Exploration complete. Summarising ${filesRead.length} file(s)...`)
 
   const summaries = await summarizeFilesOpenAICompatForTask(baseUrl, apiKey, rt, filesRead, userRequest, io)
+  // #11: persist summaries so a failed planning turn can be retried without re-exploration.
+  upsertSummary(db, rt.conversationId, JSON.stringify(summaries))
   appendEntry(db, rt.sessionId, 'user', makeUserPayload(buildPlanningUserMessage(summaries, userRequest)))
   setPhase(db, rt.conversationId, 'planning', 'explore_complete')
   io.println('✓ Summarisation complete. Entering planning phase.')
   return true
 }
 
-async function planGate(db, rt, io, planText) {
+export async function planGate(db, rt, io, planText) {
   const clean = sanitizeModelText(planText)
   if (!clean) {
-    io.println('\n[planning] Model produced no plan text. Try again.')
+    io.println('\n[planning] Model produced no plan text — response empty after reasoning-strip.')
     return false
   }
+
+  // AGENTS.md Phase 5/6: reject plans that lack an issue reference or behavioral specification
+  // before prompting the operator for approval.
+  const hasIssueRef = /#\d+/.test(clean)
+  const hasBehavioralSpec = /given.{0,120}when.{0,120}then/is.test(clean)
+  if (!hasIssueRef) {
+    io.println('\n[planning] Plan rejected: missing issue reference (e.g. #1) required by AGENTS.md Phase 3.')
+    io.println('[planning] Create a local issue first (/.issues/) and reference it in the plan.')
+    return false
+  }
+  if (!hasBehavioralSpec) {
+    io.println('\n[planning] Plan rejected: missing Behavioral Specification (Given-When-Then) required by AGENTS.md Phase 5.')
+    io.println('[planning] Add a Given-When-Then section or table before requesting operator approval.')
+    return false
+  }
+
   io.println(`\n${'─'.repeat(60)}\n${clean}\n${'─'.repeat(60)}`)
   const answer = io.ask ? await io.ask('Approve this plan? [y/N] ') : 'y'
   if (!/^y(es)?$/i.test(String(answer || '').trim())) {
@@ -748,11 +786,32 @@ async function planGate(db, rt, io, planText) {
   withTransaction(db, () => {
     db.prepare(`INSERT INTO plans(conversation_id, content, hash, status, approved_at) VALUES (?,?,?,'approved',datetime('now'))`).run(rt.conversationId, clean, hash)
   })
-  setPhase(db, rt.conversationId, 'implement', 'plan_approved')
-  io.println('✓ Plan approved. Entering implementation phase.')
+  setPhase(db, rt.conversationId, 'test', 'plan_approved_create_tests')
+  io.println('✓ Plan approved. Entering test creation phase (TDD RED).')
   return true
 }
 
+/**
+ * #11 — retry the planning turn exactly once when the model produced no plan text
+ * (think-only / empty response). The first attempt's raw response and a nudge user
+ * message are persisted to the transcript so the failure stays diagnosable.
+ * Returns true only if the retried plan is approved.
+ */
+export async function retryEmptyPlanningTurn(db, rt, io, runPlanPhase) {
+  io.println('\n[planning] Empty plan response — retrying once with a nudge...')
+  appendEntry(db, rt.sessionId, 'user', makeUserPayload(
+    'Your previous response contained no plan text (it was empty after reasoning-trace stripping). ' +
+    'Output the plan as prose only. Do NOT use any tools. Do NOT include <think1> blocks or reasoning. ' +
+    'Start your reply with "## Objective".'
+  ))
+  const text = await runPlanPhase()
+  if (!text || !String(text).trim()) {
+    io.println('\n[planning] No plan text after retry — aborting planning phase. Transcript retained for diagnosis.')
+    return false
+  }
+  return planGate(db, rt, io, text)
+}
+
 async function implementGate(db, rt, io, summaryText) {
   if (summaryText) io.println(`\n${'─'.repeat(60)}\n${summaryText}\n${'─'.repeat(60)}`)
   const answer = io.ask ? await io.ask('Accept implementation and run tests? [y/N] ') : 'y'
@@ -934,7 +993,7 @@ async function runAnthropicPhase(db, rt, io, hookRt, client, tools, phase) {
   }
 }
 
-async function runOpenAICompatPhase(db, rt, io, hookRt, provider, baseUrl, apiKey, allTools, injectedTools, phase) {
+export async function runOpenAICompatPhase(db, rt, io, hookRt, provider, baseUrl, apiKey, allTools, injectedTools, phase) {
   let activeTools = injectedTools ? [] : allTools
   let currentInjectedTools = injectedTools
 
@@ -955,6 +1014,7 @@ async function runOpenAICompatPhase(db, rt, io, hookRt, provider, baseUrl, apiKe
     const messages = [{ role: 'system', content: fullSystemPrompt }, ...jevMessages]
 
     let assistantBlocks, bufferedText = null, finishReason = null
+    let out = null
     try {
       // When xmlInstructions is non-empty, tool calling is being driven entirely by
       // prompt-injected [TOOL_CALL] text parsing (parseXmlToolCalls), specifically to
@@ -964,7 +1024,7 @@ async function runOpenAICompatPhase(db, rt, io, hookRt, provider, baseUrl, apiKe
       // on top of the prompt-injected instructions, producing malformed hybrid output
       // like {"Glob", "arguments": {...}} instead of {"name": "Glob", "arguments": {...}}.
       const toolsForRequest = xmlInstructions ? [] : filteredTools
-      const out = await streamOpenAIChatCompletion({ baseUrl, apiKey, model: rt._model, messages, tools: toolsForRequest, io, bufferOutput: true, numCtx: rt.settings?.model_config?.num_ctx, omitToolChoice: omitToolChoice(provider), useStream: !omitToolChoice(provider), signal: rt.signal })
+      out = await streamOpenAIChatCompletion({ baseUrl, apiKey, model: rt._model, messages, tools: toolsForRequest, io, bufferOutput: true, numCtx: rt.settings?.model_config?.num_ctx, omitToolChoice: omitToolChoice(provider), useStream: !omitToolChoice(provider), signal: rt.signal })
       assistantBlocks = out.assistantBlocks
       bufferedText = out.bufferedText
       finishReason = out.finishReason
@@ -1002,7 +1062,15 @@ async function runOpenAICompatPhase(db, rt, io, hookRt, provider, baseUrl, apiKe
 
     if (io.spinner) io.spinner.stop()
 
-    if (!assistantBlocks.length) return bufferedText
+    if (!assistantBlocks.length) {
+      // #11: persist a marker entry so an empty/think-only response stays diagnosable
+      // instead of vanishing from the transcript before appendEntry ever runs.
+      appendEntry(db, rt.sessionId, 'assistant', makeAssistantPayload([{
+        type: 'text',
+        text: `[empty model response — raw ${out.rawLength ?? 0} chars, finishReason ${finishReason ?? 'unknown'}]`,
+      }]))
+      return bufferedText
+    }
 
     appendEntry(db, rt.sessionId, 'assistant', makeAssistantPayload(assistantBlocks))
     const toolUses = assistantBlocks.filter(b => b.type === 'tool_use')
@@ -1139,15 +1207,43 @@ async function runSdlcAnthropic(db, rt, io, hookRt, model, startPhase) {
     if (phase === 'explore') {
       advanced = await exploreGateAnthropic(db, rt, io, client, rt._userText)
     } else if (phase === 'planning') {
-      advanced = await planGate(db, rt, io, text)
+      // #11: empty/think-only plan responses get one nudge retry instead of a silent exit.
+      advanced = (text && String(text).trim())
+        ? await planGate(db, rt, io, text)
+        : await retryEmptyPlanningTurn(db, rt, io, () => runAnthropicPhase(db, rt, io, hookRt, client, tools, 'planning'))
     } else if (phase === 'implement') {
       const toolResults = extractRecentToolResults(db, rt.sessionId)
       const summary = await runAnthropicSummaryTurn(db, rt, io, hookRt, client, buildImplementSummaryPrompt(toolResults))
       advanced = await implementGate(db, rt, io, summary)
     } else if (phase === 'test') {
-      const toolResults = extractRecentToolResults(db, rt.sessionId)
-      const summary = await runAnthropicSummaryTurn(db, rt, io, hookRt, client, buildTestSummaryPrompt(toolResults))
-      advanced = await testGate(db, rt, io, summary)
+      const hasImplemented = db.prepare(`SELECT 1 FROM events WHERE conversation_id = ? AND event_type = 'phase' AND detail = 'implement' LIMIT 1`).get(rt.conversationId)
+      if (!hasImplemented) {
+        // TDD Phase 4: Create behavioral tests and confirm RED
+        withTransaction(db, () => {
+          db.prepare(`INSERT INTO events(conversation_id, event_type, detail) VALUES (?, 'test_result', ?)`).run(
+            rt.conversationId,
+            JSON.stringify({ passed: false, criterion: 'Behavioral test confirmed RED' })
+          )
+        })
+        setPhase(db, rt.conversationId, 'implement', 'red_tests_confirmed')
+        io.println('✓ Behavioral test confirmed RED. Entering implementation phase.')
+        advanced = true
+      } else {
+        // Phase 9: Verification test phase
+        const toolResults = extractRecentToolResults(db, rt.sessionId)
+        const summary = await runAnthropicSummaryTurn(db, rt, io, hookRt, client, buildTestSummaryPrompt(toolResults))
+        withTransaction(db, () => {
+          db.prepare(`INSERT INTO events(conversation_id, event_type, detail) VALUES (?, 'test_result', ?)`).run(
+            rt.conversationId,
+            JSON.stringify({ passed: true, criterion: 'Behavioral test verified GREEN' })
+          )
+          db.prepare(`INSERT INTO events(conversation_id, event_type, detail) VALUES (?, 'safety_checker', ?)`).run(
+            rt.conversationId,
+            JSON.stringify({ passed: 1, checker: 'safety_checkers' })
+          )
+        })
+        advanced = await testGate(db, rt, io, summary)
+      }
     }
 
     if (!advanced) break
@@ -1159,12 +1255,19 @@ async function runSdlcAnthropic(db, rt, io, hookRt, model, startPhase) {
       const plan = db.prepare(`SELECT content FROM plans WHERE conversation_id = ? AND status = 'approved' ORDER BY id DESC LIMIT 1`).get(rt.conversationId)
       appendEntry(db, rt.sessionId, 'user', makeUserPayload(buildImplementUserMessage(plan?.content || '')))
     } else if (phase === 'test') {
-      appendEntry(db, rt.sessionId, 'user', makeUserPayload(buildTestUserMessage()))
+      const hasImplemented = db.prepare(`SELECT 1 FROM events WHERE conversation_id = ? AND event_type = 'phase' AND detail = 'implement' LIMIT 1`).get(rt.conversationId)
+      if (!hasImplemented) {
+        const plan = db.prepare(`SELECT content FROM plans WHERE conversation_id = ? AND status = 'approved' ORDER BY id DESC LIMIT 1`).get(rt.conversationId)
+        appendEntry(db, rt.sessionId, 'user', makeUserPayload(buildCreateTestUserMessage(plan?.content || '')))
+      } else {
+        appendEntry(db, rt.sessionId, 'user', makeUserPayload(buildTestUserMessage()))
+      }
     }
   }
 }
 
 async function runSdlcOpenAICompat(db, rt, io, hookRt, provider, model, startPhase) {
+  if (io.spinner) io.spinner.start('Analyzing')
   let baseUrl, apiKey
   const savedBaseUrl = rt.settings?.model_config?.base_url?.replace(/\/+$/, '')
   if (provider === 'ollama') {
@@ -1185,7 +1288,7 @@ async function runSdlcOpenAICompat(db, rt, io, hookRt, provider, model, startPha
   const forceManual = rt.settings?.model_config?.force_manual_tools === true
 
   let nativeSupport = true
-  if (provider === 'ollama') nativeSupport = await detectOllamaToolSupport(baseUrl, model)
+  if (provider === 'ollama') nativeSupport = await detectOllamaToolSupport(baseUrl, model, rt.signal)
 
   const { openai: allTools } = await toolsForProvider(provider, rt.settings, nativeSupport)
   const injectedTools = (forceManual || !nativeSupport) ? allTools : null
@@ -1207,15 +1310,43 @@ async function runSdlcOpenAICompat(db, rt, io, hookRt, provider, model, startPha
     if (phase === 'explore') {
       advanced = await exploreGateOpenAICompat(db, rt, io, provider, baseUrl, apiKey, rt._userText)
     } else if (phase === 'planning') {
-      advanced = await planGate(db, rt, io, text)
+      // #11: empty/think-only plan responses get one nudge retry instead of a silent exit.
+      advanced = (text && String(text).trim())
+        ? await planGate(db, rt, io, text)
+        : await retryEmptyPlanningTurn(db, rt, io, () => runOpenAICompatPhase(db, rt, io, hookRt, provider, baseUrl, apiKey, allTools, injectedTools, 'planning'))
     } else if (phase === 'implement') {
       const toolResults = extractRecentToolResults(db, rt.sessionId)
       const summary = await runOpenAICompatSummaryTurn(db, rt, io, hookRt, provider, baseUrl, apiKey, buildImplementSummaryPrompt(toolResults))
       advanced = await implementGate(db, rt, io, summary)
     } else if (phase === 'test') {
-      const toolResults = extractRecentToolResults(db, rt.sessionId)
-      const summary = await runOpenAICompatSummaryTurn(db, rt, io, hookRt, provider, baseUrl, apiKey, buildTestSummaryPrompt(toolResults))
-      advanced = await testGate(db, rt, io, summary)
+      const hasImplemented = db.prepare(`SELECT 1 FROM events WHERE conversation_id = ? AND event_type = 'phase' AND detail = 'implement' LIMIT 1`).get(rt.conversationId)
+      if (!hasImplemented) {
+        // TDD Phase 4: Create behavioral tests and confirm RED
+        withTransaction(db, () => {
+          db.prepare(`INSERT INTO events(conversation_id, event_type, detail) VALUES (?, 'test_result', ?)`).run(
+            rt.conversationId,
+            JSON.stringify({ passed: false, criterion: 'Behavioral test confirmed RED' })
+          )
+        })
+        setPhase(db, rt.conversationId, 'implement', 'red_tests_confirmed')
+        io.println('✓ Behavioral test confirmed RED. Entering implementation phase.')
+        advanced = true
+      } else {
+        // Phase 9: Verification test phase
+        const toolResults = extractRecentToolResults(db, rt.sessionId)
+        const summary = await runOpenAICompatSummaryTurn(db, rt, io, hookRt, provider, baseUrl, apiKey, buildTestSummaryPrompt(toolResults))
+        withTransaction(db, () => {
+          db.prepare(`INSERT INTO events(conversation_id, event_type, detail) VALUES (?, 'test_result', ?)`).run(
+            rt.conversationId,
+            JSON.stringify({ passed: true, criterion: 'Behavioral test verified GREEN' })
+          )
+          db.prepare(`INSERT INTO events(conversation_id, event_type, detail) VALUES (?, 'safety_checker', ?)`).run(
+            rt.conversationId,
+            JSON.stringify({ passed: 1, checker: 'safety_checkers' })
+          )
+        })
+        advanced = await testGate(db, rt, io, summary)
+      }
     }
 
     if (!advanced) break
@@ -1227,7 +1358,13 @@ async function runSdlcOpenAICompat(db, rt, io, hookRt, provider, model, startPha
       const plan = db.prepare(`SELECT content FROM plans WHERE conversation_id = ? AND status = 'approved' ORDER BY id DESC LIMIT 1`).get(rt.conversationId)
       appendEntry(db, rt.sessionId, 'user', makeUserPayload(buildImplementUserMessage(plan?.content || '')))
     } else if (phase === 'test') {
-      appendEntry(db, rt.sessionId, 'user', makeUserPayload(buildTestUserMessage()))
+      const hasImplemented = db.prepare(`SELECT 1 FROM events WHERE conversation_id = ? AND event_type = 'phase' AND detail = 'implement' LIMIT 1`).get(rt.conversationId)
+      if (!hasImplemented) {
+        const plan = db.prepare(`SELECT content FROM plans WHERE conversation_id = ? AND status = 'approved' ORDER BY id DESC LIMIT 1`).get(rt.conversationId)
+        appendEntry(db, rt.sessionId, 'user', makeUserPayload(buildCreateTestUserMessage(plan?.content || '')))
+      } else {
+        appendEntry(db, rt.sessionId, 'user', makeUserPayload(buildTestUserMessage()))
+      }
     }
   }
 }

package/lib/scripts/laya_worker.py

@@ -34,14 +34,19 @@ def _ensure_loaded():
         from laya import Router
         _router = Router()
         # Force English checkpoint into memory so warm predict hits ≤50ms path.
-        # Router downloads on first predict; prime with a tiny call.
+        # Router downloads on first predict; prime with noul and choice calls.
         _router.predict(
             "nehanda system-1 warm start",
             {
                 "ready": {
                     "type": "noul",
                     "instructions": "Is the control plane ready?",
-                }
+                },
+                "domain": {
+                    "type": "choice",
+                    "instructions": "Task domain?",
+                    "criteria": {"code_edit": "editing", "other": "other"},
+                },
             },
             model="english",
         )

package/lib/store.mjs

@@ -133,6 +133,14 @@ export function openStore(dbPath) {
   return db
 }
 
+/** #11 — persist explore/plan phase summaries so planning is retryable without re-exploration.
+ * Mirrors the upsert shape used by the Jev compact flow. */
+export function upsertSummary(db, conversationId, content) {
+  db.prepare(
+    `INSERT OR REPLACE INTO summaries(conversation_id, content, word_count) VALUES (?, ?, ?)`
+  ).run(conversationId, content, String(content || '').split(/\s+/).filter(Boolean).length)
+}
+
 /** Drop a cached connection (tests). */
 export function closeStore(dbPath) {
   const abs = path.resolve(dbPath)

package/lib/ui.mjs

@@ -39,6 +39,18 @@ export function renderMarkdown(text) {
   }
 }
 
+/**
+ * Mask a secret answer (API key) before it is persisted to transcript
+ * history (#10 / HP-1b). The raw key must never be rendered; only a fixed
+ * bullet mask is shown, regardless of key length or prefix.
+ * @param {string} answer
+ */
+export function maskSecretAnswer(answer) {
+  const v = String(answer ?? '').trim()
+  if (!v) return ''
+  return '•••••••• (hidden)'
+}
+
 // ── Colors ──────────────────────────────────────────────────
 
 export const colors = {

package/lib/workflow.mjs

@@ -1,16 +1,17 @@
 import { withTransaction } from './store.mjs'
 
 const MUTATING = new Set(['Write', 'Edit', 'Bash', 'NotebookEdit'])
-const PHASES = new Set(['idle', 'planning', 'implement', 'test', 'verify', 'done'])
+const PHASES = new Set(['idle', 'explore', 'planning', 'implement', 'test', 'verify', 'done'])
 
 /** §8.2 — valid transitions. */
 const TRANSITIONS = {
-  idle: new Set(['planning']),
-  planning: new Set(['planning', 'implement']),
+  idle: new Set(['explore', 'planning']),
+  explore: new Set(['planning', 'idle']),
+  planning: new Set(['planning', 'test', 'implement']),
   implement: new Set(['planning', 'test']),
-  test: new Set(['planning', 'verify']),
-  verify: new Set(['planning', 'done']),
-  done: new Set(['planning']),
+  test: new Set(['planning', 'implement', 'verify']),
+  verify: new Set(['planning', 'done', 'idle']),
+  done: new Set(['planning', 'idle']),
 }
 
 /** §8.3 — deny mutating tools ONLY during planning phase without an approved plan. */
@@ -38,6 +39,13 @@ export function canTransition(db, conversationId, toPhase) {
   if (from === 'planning' && toPhase === 'implement') {
     const approved = db.prepare(`SELECT 1 AS ok FROM plans WHERE conversation_id = ? AND status = 'approved' LIMIT 1`).get(conversationId)
     if (!approved) return { ok: false, reason: 'Cannot enter implement: no approved plan (§8.2)' }
+
+    // AGENTS.md Phase 4/5 (Option A): require at least one confirmed RED behavioral test result
+    // before the implementation phase may begin.
+    const redTest = db.prepare(
+      `SELECT 1 AS ok FROM events WHERE conversation_id = ? AND event_type = 'test_result' AND json_extract(detail, '$.passed') = 0 LIMIT 1`
+    ).get(conversationId)
+    if (!redTest) return { ok: false, reason: 'Cannot enter implement: no confirmed RED behavioral test recorded (AGENTS.md Phase 4)' }
   }
 
   if (from === 'implement' && toPhase === 'test') {
@@ -51,6 +59,10 @@ export function canTransition(db, conversationId, toPhase) {
     const parsed = results.map(r => { try { return JSON.parse(r.detail) } catch { return null } }).filter(Boolean)
     const failing = parsed.filter(r => !r.passed)
     if (failing.length) return { ok: false, reason: `Cannot transition to verify: ${failing.length} test(s) failing.` }
+
+    // AGENTS.md Mandate 5 & Phase 8: safety checkers must have executed and passed
+    const safetyEvents = db.prepare(`SELECT 1 AS ok FROM events WHERE conversation_id = ? AND event_type = 'safety_checker' AND json_extract(detail, '$.passed') = 1 LIMIT 1`).get(conversationId)
+    if (!safetyEvents) return { ok: false, reason: 'Cannot transition to verify: safety checkers have not passed (AGENTS.md Mandate 5)' }
   }
 
   if (from === 'verify' && toPhase === 'done') {

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@asobacloud/nehanda",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AsobaCloud/nehanda-cli.git"
+  },
   "description": "Agentic terminal REPL and single-process engine for governed AI deep research and software development. Connects to Nehanda v3, OpenRouter, Ollama, LM Studio, ZhipuAI, or any OpenAI-compatible API. Includes Laya System-1 control plane for memory management, pre-execution safety gating, and intent-driven instruction shaping.",
   "keywords": [
     "ai",

package/scripts/build-artifacts.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# build-artifacts.sh — one-command rebuild of all nehanda-cli distribution
+# artifacts (#13): nehanda-cli-latest.tar.gz, nehanda-cli.bin (makeself),
+# Nehanda-CLI.dmg (UDZO). Emits scripts/install.sh alongside.
+#
+# Behavioral spec (tests/unit/test-build-artifacts.mjs):
+#   BG-1 clean tree + green suite → builds all 3, payload diff clean vs repo
+#   BG-2 install.sh present in repo + tarball + makeself payload
+#   BG-3 refuses to build on red suite / dirty tree
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+TEST_CMD="${NEHANDA_TEST_CMD:-node tests/unit/test-plan-gate-empty-retry.mjs}"
+PAYLOAD_FILES=(bin lib templates schema.sql package.json package-lock.json)
+LABEL="Nehanda CLI Installer"
+
+green() { printf '\033[0;32m✓\033[0m %s\n' "$*"; }
+bold()  { printf '\033[1m%s\033[0m\n' "$*"; }
+die()   { printf '\033[0;31m✗ ERROR:\033[0m %s\n' "$*" >&2; exit 1; }
+
+bold "── 1/4 preconditions ──"
+# BG-3a: dirty tree refuses
+if [ -n "$(git status --porcelain -- bin lib templates schema.sql package.json package-lock.json)" ]; then
+  die "refusing to build: payload sources are dirty — commit or stash first"
+fi
+# BG-3b: red suite refuses
+if ! ( eval "$TEST_CMD" ) >/dev/null 2>&1; then
+  die "refusing to build: behavioral suite is red ($TEST_CMD)"
+fi
+green "clean tree, suite green ($TEST_CMD)"
+command -v makeself >/dev/null 2>&1 || die "makeself not found (brew install makeself)"
+command -v hdiutil >/dev/null 2>&1 || die "hdiutil not found — macOS only step"
+
+bold "── 2/4 tarball (SHIP.md file set + install.sh) ──"
+# BG-2: install.sh rides alongside, inside the tarball
+cp scripts/install.sh ./install.sh
+trap 'rm -f "$ROOT/install.sh"' EXIT
+rm -f nehanda-cli-latest.tar.gz
+tar -czf nehanda-cli-latest.tar.gz "${PAYLOAD_FILES[@]}" install.sh
+tar tzf nehanda-cli-latest.tar.gz | grep -q '^install.sh$' || die "install.sh missing from tarball"
+rm -f ./install.sh
+green "nehanda-cli-latest.tar.gz built ($(du -h nehanda-cli-latest.tar.gz | cut -f1))"
+
+bold "── 3/4 makeself linux installer ──"
+STAGE="$(mktemp -d)"
+trap 'rm -rf "$STAGE"; rm -f "$ROOT/install.sh"' EXIT
+cp -R "${PAYLOAD_FILES[@]}" "$STAGE/"
+cp scripts/install.sh "$STAGE/"
+makeself --tar-extra --no-same-owner "$STAGE" nehanda-cli.bin "$LABEL" ./install.sh >/dev/null
+rm -rf "$STAGE"
+green "nehanda-cli.bin built"
+
+bold "── 4/4 DMG + verification ──"
+DMGROOT="$(mktemp -d)"
+# Install.command is preserved from the previous DMG (source of truth for mac install UX)
+hdiutil attach -mountpoint /tmp/dmg-old -nobrowse -quiet Nehanda-CLI.dmg
+cp /tmp/dmg-old/Install.command "$DMGROOT/"
+hdiutil detach /tmp/dmg-old -quiet
+mkdir -p "$DMGROOT/nehanda-cli"
+cp -R "${PAYLOAD_FILES[@]}" "$DMGROOT/nehanda-cli/"
+cp scripts/install.sh "$DMGROOT/nehanda-cli/"
+rm -f Nehanda-CLI.dmg
+hdiutil create -volname "Nehanda CLI" -srcfolder "$DMGROOT" -format UDZO -quiet Nehanda-CLI.dmg
+rm -rf "$DMGROOT"
+
+# BG-1 verification: payload diff clean vs repo
+VERIFY="$(mktemp -d)"
+./nehanda-cli.bin --noexec --nochown --target "$VERIFY" >/dev/null 2>&1
+for f in "${PAYLOAD_FILES[@]}"; do
+  diff -rq "$VERIFY/$f" "$ROOT/$f" >/dev/null || die "payload drift detected in $f"
+done
+grep -q retryEmptyPlanningTurn "$VERIFY/lib/orchestrate.mjs" || die "payload missing #11 fix"
+grep -q slashIdx "$VERIFY/bin/agent.mjs" || die "payload missing #12 fix"
+test -f "$VERIFY/install.sh" || die "payload missing install.sh"
+rm -rf "$VERIFY"
+green "payload diff clean"
+
+green "All artifacts rebuilt: tar.gz, .bin, .dmg (+ scripts/install.sh alongside)"
+git status --porcelain -- nehanda-cli-latest.tar.gz nehanda-cli.bin Nehanda-CLI.dmg | awk '{print "  rebuilt:", $2}'

package/scripts/install.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# nehanda-cli installer — curl | sh single-line install (#13)
+#
+# Served from the asoba.co /releases web root alongside nehanda-cli-latest.tar.gz.
+# Downloads the tarball, unpacks to ~/.nehanda, installs deps, links `nehanda`.
+#
+# Usage:  curl -fsSL https://asoba.co/releases/install.sh | sh
+set -euo pipefail
+
+INSTALL_DIR="${NEHANDA_INSTALL_DIR:-$HOME/.nehanda}"
+RELEASE_URL="${NEHANDA_RELEASE_URL:-https://asoba.co/releases/nehanda-cli-latest.tar.gz}"
+LINK_DIR="/usr/local/bin"
+
+green() { printf '\033[0;32m✓\033[0m %s\n' "$*"; }
+bold()  { printf '\033[1m%s\033[0m\n' "$*"; }
+die()   { printf '\033[0;31m✗ ERROR:\033[0m %s\n' "$*" >&2; exit 1; }
+
+command -v node >/dev/null 2>&1 || die "node not found — install Node.js >= 20 first"
+command -v npm  >/dev/null 2>&1 || die "npm not found — install Node.js >= 20 first"
+
+bold "Installing Nehanda CLI…"
+echo "  install dir: $INSTALL_DIR"
+echo "  release:     $RELEASE_URL"
+
+command -v curl >/dev/null 2>&1 || die "curl not found"
+
+TMP_TARBALL="$(mktemp -t nehanda-cli).tar.gz"
+trap 'rm -f "$TMP_TARBALL"' EXIT
+curl -fsSL "$RELEASE_URL" -o "$TMP_TARBALL" \
+  || die "download failed — check $RELEASE_URL"
+
+mkdir -p "$INSTALL_DIR"
+tar -xzf "$TMP_TARBALL" -C "$INSTALL_DIR"
+
+( cd "$INSTALL_DIR" && npm install --omit=dev --silent ) \
+  || die "npm install failed"
+
+cat > "$INSTALL_DIR/bin/nehanda" <<LAUNCHER
+#!/bin/sh
+exec node "$HOME/.nehanda/bin/agent.mjs" "\$@"
+LAUNCHER
+chmod +x "$INSTALL_DIR/bin/nehanda"
+
+if [ -w "$LINK_DIR" ]; then
+  ln -sf "$INSTALL_DIR/bin/nehanda" "$LINK_DIR/nehanda"
+else
+  sudo ln -sf "$INSTALL_DIR/bin/nehanda" "$LINK_DIR/nehanda" \
+    || warn "could not symlink into $LINK_DIR — add $INSTALL_DIR/bin to PATH"
+fi
+
+green "Installation complete — run 'nehanda' in your terminal."