thincoder 0.8.10 → 0.8.11

package/README.md

@@ -205,6 +205,11 @@ Code conventions: pure `.mjs`, no semicolons, no npm dependencies allowed (inclu
 
 ## Changelog
 
+### 0.8.11 (2026-07)
+- **Feat**: `checklist` tool — persistent project task tracking in `.thincoder/checklist.md`. Add/mark/list items, auto-archive done items to `checklist-done.md`. Injected at session start (pending + in_progress only)
+- **Feat**: updated prompts — four-step workflow (requirements→design→development→testing), three-step debugging strategy (logs→docs→binary search), working checklist discipline
+- **Feat**: methodology docs — `docs/design/METHODOLOGY.md` rebuilt, `PHILOSOPHY.md` expanded with worldview #6 (official docs over guessing)
+
 ### 0.8.10 (2026-07)
 - **Bugfix**: pasted text now lands in the active TUI text target — the API key prompt when adding a provider via `/model` (and any free-text `askQuestion`) now accepts paste correctly. Previously, bracketed-paste injection in the terminal was always written to the main input box, so pasting into a question prompt appeared as "nothing happened" and orphaned the text into the input box after the question closed. Both bracketed-paste (Windows Terminal / most modern terminals) and Ctrl+V-as-key-event (legacy conhost) now route through a single `insertPastedText` helper that targets the question answer, options-list (ignored), or main input box as appropriate
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.8.10",
+  "version": "0.8.11",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/agent/helpers.mjs

@@ -2,7 +2,7 @@
  * agent/helpers.mjs — Agent utility functions and constants
  */
 import { configDir } from "../config.mjs"
-import { readFileSync, readdirSync } from "node:fs"
+import { readFileSync, readdirSync, existsSync } from "node:fs"
 import { writeFile, mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import { execSync } from "node:child_process"

package/src/agent/setup.mjs

@@ -92,6 +92,18 @@ export async function prepareRun(agent, input, callbacks, {
         content: `[System reminder: current time is ${new Date().toISOString()}.]`,
         transient: true,
       })
+      // Checklist injection: inject pending + in_progress items from .thincoder/checklist.md
+      try {
+        const { pendingItems } = await import("../tools/checklist.mjs")
+        const items = pendingItems(agent.cwd)
+        if (items.length > 0) {
+          agent.history.push({
+            role: "user",
+            content: `[System reminder: task checklist (pending/in-progress):\n${items.map(i => `- [${i.status === "in_progress" ? "~" : " "}] ${i.text}`).join("\n")}]`,
+            transient: true,
+          })
+        }
+      } catch { /* checklist not available — suppress error */ }
     }
     agent.history.push({ role: "user", content: input })
   }

package/src/prompts/discipline.md

@@ -1,4 +1,10 @@
 Coding discipline (rigor over speed—tokens spent on verification are well spent):
+
+**Workflow — never skip steps:**
+- Before writing code: 1) Requirements — clarify what's needed, write user stories, confirm. 2) Design — plan architecture and approach, write a design doc. 3) Development — write code. 4) Testing — write test cases covering normal, boundary, and error cases. Documents are required for steps 1, 2, and 4. Requirements are not complete until checklist entries exist for every requirement point — use `checklist add` to create them. Skipping straight to step 3 is wrong ten times out of nine.
+- Maintain a visible checklist for every task in `.thincoder/checklist.md` using the `checklist` tool. Checklist entries map to requirement/design points from the project's docs — project-level tracking. After requirements are confirmed, add one entry per requirement point. When you start working on an item, mark it in_progress. When it's verified complete, mark it done. Do not rely on context memory — context compresses, the checklist persists.
+
+**Coding rules:**
 - **Prefer built-in tools over bash for file operations**: use `ls` (not `bash ls`), `glob` (not `bash find`), `grep` (not `bash grep`). The bash tool runs the system shell — on Windows this is cmd.exe without Unix commands; on Unix it may have them but built-in tools are more reliable and platform-consistent.
 - Spec before code: when the user describes a feature request without specifying the details (retry count? timeout? which error types? which files?), ask clarifying questions before writing code.
 - Design docs are the spec: when the project has design documents (check with `doc_search`), read them before implementing. Their decisions represent intentional architecture — don't override them with personal habit or guesswork.
@@ -32,9 +38,10 @@ Testing discipline (right check at the right time — don't run the full suite f
 - If verify reports syntax errors or test failures, fix them before claiming completion — never mark work done with known failures
 - When you change behavior or add code, add at least one test that covers the change. If the project has no test suite yet, note that in your report. Never skip this step — untested code is incomplete code.
 
-Debugging strategy (when something goes wrong, diagnose before treating):
-- Read the FULL error output — the root cause is often at the end, not the first line
-- Don't change multiple things at once hoping one works — that destroys the signal
-- Narrow down systematically: reproduce the failure in isolation, read the file you just wrote to confirm it matches your intent, trace the control flow with grep or code_search, then fix ONE thing and re-run
-- If the error message is unclear, search the web for it before guessing at a fix
+Debugging strategy (when something goes wrong, three steps before anything else):
+- Step 1 — **Read logs**: read the FULL error output. The root cause is often at the end, not the first line. Don't skip, don't guess.
+- Step 2 — **Check docs**: if the error message is unclear, search official docs (websearch/fetch) before guessing at a fix. Don't build theories in isolation.
+- Step 3 — **Binary search**: cut the problem space in half, test which half contains the fault, repeat. Don't try to find the answer in one jump.
+- After the three steps: reproduce the failure in isolation, fix ONE thing, re-run. Don't change multiple things at once — that destroys the signal.
+- Don't get stuck reading code for long stretches. What you can't understand by reading, understand by running: write a test, add a log, use binary search. Acting beats staring.
 - Distinguish root causes from proximate causes: if your own behavior was wrong, ask what caused it — did the prompt mislead you? is there a contradiction in the rules? was a tool description ambiguous? Fix the system, not just the symptom.

package/src/provider/core.mjs

@@ -155,7 +155,7 @@ async function requestWithRetry(provider, body, signal, onWait) {
 
     const text = await response.text().catch(() => "")
     const message = `LLM API error ${response.status}: ${text}`
-    if (isQuotaError(text)) throw new Error(message)
+    if (isNonRetryableError(response.status, text)) throw new Error(message)
     if (response.status === 429) {
       const retryAfter = Number(response.headers.get("retry-after"))
       const waitMs =
@@ -179,19 +179,39 @@ async function requestWithRetry(provider, body, signal, onWait) {
   throw lastError
 }
 
-function isQuotaError(text) {
-  try {
-    const type = JSON.parse(text)?.error?.type
-    return typeof type === "string" && type.includes("quota")
-  } catch {
-    return false
+/**
+ * Detect errors that should NOT be retried — quota, billing, auth, invalid params.
+ * Different providers use wildly different error formats. Check body text for known patterns.
+ */
+function isNonRetryableError(status, text) {
+  // Auth errors: never retry
+  if (status === 401 || status === 403) return true
+  // 400-level non-429: usually invalid params
+  if (status >= 400 && status < 500 && status !== 429) return true
+  // For 429, check if it's actually a billing/quota error (not rate limit)
+  if (status === 429) {
+    const lower = text.toLowerCase()
+    // Chinese providers often return 429 for billing issues
+    if (lower.includes("余额不足") || lower.includes("余额") || lower.includes("充值")) return true
+    if (lower.includes("insufficient") && (lower.includes("balance") || lower.includes("quota") || lower.includes("credit"))) return true
+    if (lower.includes("quota") && (lower.includes("exceeded") || lower.includes("insufficient"))) return true
+    // Standard OpenAI billing error (error.type === "insufficient_quota" or similar)
+    try {
+      const j = JSON.parse(text)
+      const errType = j?.error?.type || ""
+      if (typeof errType === "string" && (errType.includes("quota") || errType.includes("billing") || errType.includes("insufficient") || errType.includes("balance"))) return true
+      const errCode = j?.error?.code || ""
+      if (typeof errCode === "string" && (errCode === "1113" || errCode === "1114")) return true // GLM billing codes
+    } catch {}
   }
+  return false
 }
 
 async function readSSE(response, { onToken, onReasoning }) {
   const result = { content: "", reasoning: "", toolCalls: [], usage: null, finishReason: null }
   const decoder = new TextDecoder()
   let buffer = ""
+  let hasChoices = false
 
   const processLines = (lines) => {
     for (const line of lines) {
@@ -205,6 +225,7 @@ async function readSSE(response, { onToken, onReasoning }) {
       if (json.usage) result.usage = json.usage
       const choice = json.choices?.[0]
       if (!choice) continue
+      hasChoices = true
       if (choice.finish_reason) result.finishReason = choice.finish_reason
 
       const delta = choice.delta ?? {}
@@ -234,6 +255,31 @@ async function readSSE(response, { onToken, onReasoning }) {
   }
   buffer += decoder.decode()
   processLines(buffer.split("\n"))
+
+  // If no SSE choices were found, the response is likely a JSON error
+  if (!hasChoices) {
+    const contentType = response.headers.get("content-type") || ""
+    let errorMsg = ""
+    try {
+      const raw = buffer.trim() || ""
+      if (raw) {
+        const parsed = JSON.parse(raw)
+        errorMsg = parsed?.error?.message
+          || parsed?.base_resp?.status_msg
+          || parsed?.detail
+          || parsed?.message
+          || parsed?.msg
+          || (typeof parsed.error === "string" ? parsed.error : "")
+      }
+    } catch { /* not JSON */ }
+    if (!errorMsg && !contentType.includes("event-stream")) {
+      errorMsg = `Response is not SSE (Content-Type: ${contentType || "unknown"})`
+    }
+    if (errorMsg) {
+      throw new Error(`API error: ${errorMsg}`)
+    }
+  }
+
   return result
 }
 

package/src/tools/checklist.md

@@ -0,0 +1,7 @@
+Manage the task checklist in .thincoder/checklist.md. Use at these points: after requirements are confirmed — add one entry per requirement point; when starting work — mark in_progress; when verified complete — mark done. Checklist entries map to requirement/design points — project-level tracking across sessions. For in-session subtask breakdown of a single checklist item, use the `task` tool instead. Completed items are auto-archived to .thincoder/checklist-done.md.
+
+Parameters:
+- action: "add" | "mark" | "list"
+- item: text for new item (with "add")
+- index: 1-based index (with "mark")
+- status: "pending" | "in_progress" | "done" (with "mark")

package/src/tools/checklist.mjs

@@ -0,0 +1,114 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { DESC } from "./shared.mjs"
+
+const CHECKLIST = "checklist.md"
+const DONE = "checklist-done.md"
+
+function checklistPath(cwd) { return join(cwd, ".thincoder", CHECKLIST) }
+function donePath(cwd) { return join(cwd, ".thincoder", DONE) }
+
+/** Parse checklist file into array of { index, status, text } */
+function parse(filePath) {
+  if (!existsSync(filePath)) return []
+  const lines = readFileSync(filePath, "utf-8").split("\n")
+  const items = []
+  let idx = 0
+  for (const line of lines) {
+    const m = line.match(/^- \[(.)\] (.+)$/)
+    if (m) {
+      idx++
+      const raw = m[1]
+      const status = raw === "x" ? "done" : raw === "~" ? "in_progress" : "pending"
+      items.push({ index: idx, status, text: m[2].trim() })
+    }
+  }
+  return items
+}
+
+/** Write items back to file */
+function write(filePath, items) {
+  mkdirSync(dirname(filePath), { recursive: true })
+  const lines = []
+  for (const item of items) {
+    const mark = item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "
+    lines.push(`- [${mark}] ${item.text}`)
+  }
+  writeFileSync(filePath, lines.join("\n") + "\n")
+}
+
+/** Parse pending items only (for context injection) */
+export function pendingItems(cwd) {
+  return parse(checklistPath(cwd)).filter(i => i.status !== "done")
+}
+
+export const checklistTool = {
+  name: "checklist",
+  description: DESC("checklist"),
+  parameters: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["add", "mark", "list"],
+        description: "add a new item / mark item status / list all items"
+      },
+      item: {
+        type: "string",
+        description: "Item text (required for add)"
+      },
+      index: {
+        type: "number",
+        description: "1-based item index (required for mark)"
+      },
+      status: {
+        type: "string",
+        enum: ["pending", "in_progress", "done"],
+        description: "New status (required for mark)"
+      },
+    },
+    required: ["action"],
+  },
+  readonly: false,
+  execute(args, ctx) {
+    switch (args.action) {
+      case "add": {
+        if (!args.item || typeof args.item !== "string") return "Error: 'item' is required for add"
+        const items = parse(checklistPath(ctx.cwd))
+        items.push({ index: items.length + 1, status: "pending", text: args.item })
+        write(checklistPath(ctx.cwd), items)
+        return `Added: [ ] ${args.item}`
+      }
+      case "mark": {
+        if (args.index == null) return "Error: 'index' is required for mark"
+        const status = args.status
+        if (!status || !["pending", "in_progress", "done"].includes(status)) return "Error: 'status' is required (pending|in_progress|done)"
+        const cp = checklistPath(ctx.cwd)
+        const items = parse(cp)
+        if (args.index < 1 || args.index > items.length) return `Error: index ${args.index} out of range (1-${items.length})`
+        const item = items[args.index - 1]
+        const old = item.status
+        if (old === status) return `Already ${status}: ${item.text}`
+        item.status = status
+        if (status === "done") {
+          // Move to done file
+          const dp = donePath(ctx.cwd)
+          const doneItems = parse(dp)
+          doneItems.push(item)
+          write(dp, doneItems)
+          items.splice(args.index - 1, 1)
+        }
+        write(cp, items)
+        return `Marked #${args.index} ${old} → ${status}: ${item.text}`
+      }
+      case "list": {
+        const items = parse(checklistPath(ctx.cwd))
+        if (items.length === 0) return "(checklist is empty)"
+        const marks = { pending: " ", in_progress: "~", done: "x" }
+        return items.map(i => `- [${marks[i.status]}] ${i.text}`).join("\n")
+      }
+      default:
+        return `Error: unknown action '${args.action}'`
+    }
+  },
+}

package/src/tools/index.mjs

@@ -6,12 +6,14 @@ import { applyPatchTool, syntaxCheckTool, deleteTool } from "./patch.mjs";
 import { bashTool, globTool, grepTool, lsTool } from "./system.mjs";
 import { websearchTool, fetchTool } from "./web.mjs";
 import { gitDiffTool, gitStatusTool, gitLogTool, questionTool, checkpointTool } from "./git.mjs";
+import { checklistTool } from "./checklist.mjs";
 
 export const builtinTools = [
   readTool, writeTool, editTool, insertAfterTool, applyPatchTool,
   syntaxCheckTool, readImageTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
   gitDiffTool, gitStatusTool, gitLogTool, questionTool, checkpointTool,
+  checklistTool,
 ];
 
 export {