thincoder 0.12.49 → 0.12.50

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 本文件记录 ThinCoder CLI 的发布历史。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，版本遵循[语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.12.50] — 2026-08-29
+
+### Changed
+
+- **engineering 与 advisor.guard 改为会话级（跨端污染修复）**：旧设计里 engineering 只存 config.json 全局（`agent.engineering`），CLI `/eng` 与 VS Code 面板都写它 → 两端互相翻转对方的工程模式（"VS Code 工程模式下模型仍委托 role='coder'"）。现事实源是当前会话槽位文件（`engineering` 字段 + `advisor.guard`），config.json 降为 CLI 兼容/可见性镜像（双写保留：slot 先、config 后，slot 失败不阻断）。改动：`/eng` toggle 双写 slot（`cmd-eng.mjs` persistEngineering）；`/advisor` guard 切换双写 slot（`cmd-advisor.mjs` persistGuard，model/thinking 仍 config-scoped）；`saveSession`/`applySession` 往返 slot 值（无字段旧槽位回退 config，兼容锁定）；启动恢复链 `bin/thincoder.mjs` applySession 时 slot 覆盖 config 播种值。权威文档：`docs/design/ENGINEERING-MODE.md` §5 重写
+- **METHODOLOGY 三缺口修复**（核对工程模式提示词时发现）：① 需求文档三层结构（总目标/功能用户故事/非功能标准）落地进 METHODOLOGY.md 与 methodology-template.md——engineering.md 的 "three layers per METHODOLOGY" 引用此前悬空；② engineering.md 交付评审补测试文档口径（METHODOLOGY 存在时每条用户故事须有测试用例覆盖正常/边界/异常，无覆盖=评审不通过）——与三文档硬流程对齐；③ METHODOLOGY.md 缺失警告点名后果（引用悬空+硬流程失效+恢复路径），不再静默降级
+- **工程模式 UI/交互决策全链路落档**（用户报告"agent 无视讨论过的 UI 设计"）：设计文档要素扩项——涉及界面时必须收录与用户达成的每条 UI/交互决策（布局/流程/控件行为/状态反馈），未定标 open 不静默发明；eng-coder 任务书必须复述这些决策（或指向设计文档具体章节）——子代理零上下文，留在聊天里的决策永远到不了它；`eng-coder.md` 执行侧闭合——缺失的界面决策停下报告，不自行发明。两端 prompts byte-identical；`ENGINEERING-MODE.md` §7 变更记录
+
+### Tests
+
+- 新增 `test/session-eng-advisor.test.mjs`：/eng 双写断言（slot+config）、applySession slot 恢复（true/false/显式 false 压过 config true）、旧槽位无字段回退 config 锁定、saveSession 每 turn 往返、/advisor guard 双写（model 等仍 config-scoped）
+
 ## [0.12.49] — 2026-08-29
 
 ### Added

package/package.json

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

package/src/agent/setup.mjs

@@ -252,12 +252,12 @@ export async function prepareRun(agent, input, callbacks, {
         warnings.push(`Engineering template (${agent._role === "eng-coder" ? "engineering-sub.md" : "engineering.md"}) not found — using degraded constraints.`)
       }
       if (engResult.methodologyMissing) {
-        warnings.push("METHODOLOGY.md not found — project-specific rules are absent.")
+        warnings.push("METHODOLOGY.md not found in the project root — no project methodology is loaded, so every 'per METHODOLOGY' reference in the engineering prompt is dangling and the three-document hard flow (requirements / design / test doc) is NOT enforced. Ask the user whether to create METHODOLOGY.md (scaffold available as src/prompts/methodology-template.md) before designing.")
       }
       if (warnings.length > 0) {
         agent.history.push({
           role: "user",
-          content: `[System reminder: ENGINEERING MODE is active but ${warnings.join(" ")} Create METHODOLOGY.md and ensure prompt templates exist for full enforcement, or disable engineering mode (/eng).]`,
+          content: `[System reminder: ENGINEERING MODE is active but ${warnings.join(" ")}]`,
         })
       }
     }

package/src/prompts/eng-coder.md

@@ -14,6 +14,7 @@ The parent agent ran an independent design review (`advisor` with `type="design"
 
 - Work independently. The parent only sees your final report.
 - Follow the design document. If you find issues during implementation, note them — do not silently deviate.
+- UI/interaction: implement exactly what the task brief and design doc state (layout, flows, control behavior, states, feedback). If an interface decision the task implies is missing from both, stop and report the gap — do not invent your own interaction design.
 - Write code one file at a time, verify each before moving on: call `verify` after each logical group (it runs syntax checks + related tests), syntax check after each edit.
 - Do not modify any file not listed in the design.
 - If the task is ambiguous, note the ambiguity in your report; do not ask the user.

package/src/prompts/engineering.md

@@ -35,7 +35,11 @@ subagents only.
      discipline.
 2. **Design.** Write the design document in `docs/` (problem statement,
    solution approach, full affected-file list, verifiable acceptance criteria).
-   Do NOT open any code file for editing before this document exists.
+   When the task involves a user interface, the design document MUST also
+   capture every UI/interaction decision agreed with the user — layout, flows,
+   control behavior, states and feedback — exactly as discussed; parts not yet
+   decided are marked open, never silently invented. Do NOT open any code file
+   for editing before this document exists.
 3. **Remind readiness — never self-initiate review.** Present the design
    summary and say it is ready for review, then WAIT. You do NOT call the
    advisor yourself — the initiation right belongs to the user: you prepare
@@ -59,15 +63,21 @@ subagents only.
 6. **Implement via eng-coder.** Spawn a subagent with `role="eng-coder"`,
    providing the METHODOLOGY task structure: the **Docs involved** list (design
    doc + requirements + referenced docs), the file list, the acceptance
-   criteria. Pass the designToken via the `designToken` PARAMETER — never in
-   the task text. The token is required — eng-coder cannot modify files
-   without it.
+   criteria. When the task has UI, the task text MUST restate the agreed
+   UI/interaction decisions (or point to the exact design-doc sections that
+   hold them) — an eng-coder has NO conversation context, so a decision that
+   lives only in the chat never reaches it. Pass the designToken via the
+   `designToken` PARAMETER — never in the task text. The token is required —
+   eng-coder cannot modify files without it.
 7. **Delivery review — automatic flow node.** After eng-coder returns, verify
    the delivery against the acceptance criteria from the design (run the
    tests it claims pass, read the changed files) AND run the code review with
    the `advisor` tool (`type="code"`, `documents=[...]` = the task's Docs
    involved list). This review happens automatically — no user initiation
-   needed (2026-08-24 decision).
+   needed (2026-08-24 decision). When METHODOLOGY.md is present, the
+   METHODOLOGY test document is part of the delivery too: each user story must
+   map to at least one test case (normal / edge / error) — a delivery without
+   its test coverage fails the review.
 8. **Verify.** Run `verify` — it must pass before you claim the task complete.
 
 ## Work Loop (every user message)
@@ -136,6 +146,11 @@ cannot enumerate. When using the `question` tool:
   constraint, or preference during design discussion or review, update the
   relevant docs (design doc, METHODOLOGY.md, ENGINEERING-MODE.md) right away —
   do not wait to be asked. A decision that isn't in a doc didn't land.
+- **UI/interaction decisions ride the full chain**: every UI/interaction
+  decision agreed with the user MUST land in the design document AND be
+  restated in the eng-coder task (or pointer to its exact design-doc section).
+  "Discussed but not written down" is the most common reason an implementation
+  ignores what the user asked for — the subagent never saw the discussion.
 - Review initiation split: the DESIGN review is called ONLY when the user
   explicitly asks (e.g. "评审吧") — remind them when the design is ready,
   never fire it yourself; each round of findings goes back to the user for

package/src/prompts/methodology-template.md

@@ -8,10 +8,15 @@
 
 Every task follows four steps, no skipping:
 
-1. **Requirements** — Discuss and document what's needed. Use user stories: **As a [role], I want [feature], so that [goal]**. Describe who / what / why — never how. After confirming requirements, create a checklist entry for each one. No checklist entry means the requirement hasn't landed yet.
-2. **Design** — Write a design document covering approach, architecture, and implementation plan. Design is approved before coding starts.
+1. **Requirements** — Discuss and document what's needed, then write the requirements doc organized in **three layers**:
+   - **Overall goal** — one sentence: what problem does this task solve, for whom;
+   - **Functional user stories** — individually acceptable, format: **As a [role], I want [feature], so that [goal]**. Describe who / what / why — never how;
+   - **Non-functional standards** — performance, security, compatibility, usability constraints, each with how it will be measured.
+
+   Requirements are DONE when all three layers are concrete enough to design against (the user confirms, or the answers stop changing the requirement). After confirming, create a checklist entry for each story. No checklist entry means the requirement hasn't landed yet.
+2. **Design** — Write a design document: problem statement, approach and rationale, full affected-file list, and verifiable acceptance criteria (each criterion traces back to a user story). Design is approved before coding starts.
 3. **Implementation** — Write the code.
-4. **Testing** — Verify. Each user story maps to at least one test case covering normal path, edge cases, and error conditions. Describe what to test, what input to give, and what output to expect.
+4. **Testing** — Verify with a test document: each user story maps to at least one test case covering normal path, edge cases, and error conditions. Describe what to test, what input to give, and what output to expect.
 
 These four steps are not "best practice" — they are hard process. Three documents required: **requirements doc**, **design doc**, **test doc**. Skipping to step 3 and writing code first is wrong nine times out of ten.
 

package/src/session.mjs

@@ -44,6 +44,7 @@ export function sessionPath(cwd) {
 }
 
 function slotPath(cwd, n) { return sessionPath(cwd) + "." + n }
+export { slotPath }
 function manifestPath(cwd) { return sessionPath(cwd) + ".manifest" }
 
 /** Path to the active slot's file */
@@ -417,6 +418,13 @@ export function applySession(agent, data) {
   agent._pendingReminders = data.pendingReminders ?? []
   agent._sessionStart = data.sessionStart ?? null
   agent._engDesignToken = data.engDesignToken ?? null
+  // engineering is session-level (2026-08-29): the slot value is the CLI session's authority
+  // — config.json is only the initial default / cross-end mirror. A legacy slot without the
+  // field keeps whatever config.json seeded (unchanged behavior).
+  if (data.engineering !== undefined) {
+    agent.config.agent ??= {}
+    agent.config.agent.engineering = data.engineering === true
+  }
   if (data.advisor) {
     agent.config.advisor = { ...data.advisor }
   }

package/src/tui/cmd-advisor.mjs

@@ -1,7 +1,10 @@
 /** /advisor command: configure review model/thinking and toggle the review guard.
  *  Interactive loop UX — stays in menu after each action, Esc to exit.
  *  ctx: { agent, showPicker, pushLine, pushLabel, persistRaw } */
+import { readFileSync } from "node:fs"
 import { ansi, C } from "./ansi.mjs"
+import { activeSlot, slotPath } from "../session.mjs"
+import { writeSessionFile } from "./cmd-eng.mjs"
 
 export async function handleAdvisorCommand(ctx) {
   const { agent, showPicker, pushLine, pushLabel } = ctx
@@ -19,6 +22,21 @@ export async function handleAdvisorCommand(ctx) {
     }
   }
 
+  // Guard-only dual write (2026-08-29 — advisor.guard is session-level): the guard goes into
+  // the CURRENT session slot first (shared with VS Code), the config.json mirror follows.
+  // Other advisor keys (model/thinking/effort/timeout) stay config-scoped — persist() only.
+  const persistGuard = async () => {
+    try {
+      const p = slotPath(agent.cwd, activeSlot(agent.cwd))
+      const data = JSON.parse(readFileSync(p, "utf8"))
+      if (data && typeof data === "object" && Array.isArray(data.history)) {
+        data.advisor = { ...(typeof data.advisor === "object" && data.advisor !== null ? data.advisor : {}), guard: cfg.guard === true }
+        writeSessionFile(p, data)
+      }
+    } catch { /* slot missing/unreadable — config mirror still written */ }
+    await persist()
+  }
+
   // Lazy model cache — fetched once per /advisor session
   let modelCache = null
 
@@ -133,9 +151,9 @@ export async function handleAdvisorCommand(ctx) {
 
     if (choice.action === "guard") {
       cfg.guard = !(cfg.guard === true)
-      await persist().catch(err => pushLine(`[error] ${err.message}`, C.error))
+      await persistGuard().catch(err => pushLine(`[error] ${err.message}`, C.error))
       pushLabel("❯ Advisor", ansi.bold + C.tool)
-      pushLine(`Advisor: ${cfg.guard === true ? "on" : "off"}`, C.tool)
+      pushLine(`Advisor: ${cfg.guard === true ? "on" : "off"} (session)`, C.tool)
       continue
     }
 

package/src/tui/cmd-eng.mjs

@@ -1,14 +1,29 @@
 /** /eng command: toggle engineering mode.
  *  Requires METHODOLOGY.md in project root. Offers to create one if missing.
  *  ctx: { agent, pushLine, pushLabel, persistRaw, showPicker } */
-import { existsSync, copyFileSync } from "node:fs"
-import { join } from "node:path"
+import { existsSync, copyFileSync, readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from "node:fs"
+import { join, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
 import { ansi, C } from "./ansi.mjs"
+import { activeSlot, slotPath } from "../session.mjs"
 
 const templateDir = join(fileURLToPath(import.meta.url), "..", "..", "prompts")
 import { ENG_OFF_REMINDER } from "../agent.mjs"
 
+/** Atomic slot write (same shape as session.mjs writeSessionFile — kept local to avoid a
+ *  private-import; cmd-advisor's guard toggle shares this helper). */
+export function writeSessionFile(p, data) {
+  mkdirSync(dirname(p), { recursive: true })
+  const tmp = `${p}.tmp`
+  writeFileSync(tmp, JSON.stringify(data), "utf8")
+  try {
+    renameSync(tmp, p)
+  } catch {
+    try { unlinkSync(p) } catch {}
+    try { renameSync(tmp, p) } catch { writeFileSync(p, readFileSync(tmp, "utf8"), "utf8") }
+  }
+}
+
 export async function handleEngCommand(ctx) {
   const { agent, pushLine, pushLabel, persistRaw, showPicker } = ctx
   agent.config.agent ??= {}
@@ -40,13 +55,35 @@ export async function handleEngCommand(ctx) {
     agent._pendingReminders = agent._pendingReminders ?? []
     agent._pendingReminders.push(ENG_OFF_REMINDER)
   }
-  await persistRaw((raw) => {
-    raw.agent ??= {}
-    raw.agent.engineering = agent.config.agent.engineering
-  })
+  await persistEngineering(ctx, agent)
   pushLabel("❯ Eng", ansi.bold + C.tool)
-  pushLine(`Engineering mode: ${agent.config.agent.engineering ? "ON" : "OFF"}`, C.tool)
+  pushLine(`Engineering mode: ${agent.config.agent.engineering ? "ON" : "OFF"} (session)`, C.tool)
   if (agent.config.agent.engineering) {
     pushLine(`  → strictly following ${methodologyPath}`, C.dim)
   }
 }
+
+/**
+ * Dual persistence (2026-08-29 — engineering is session-level): write the flipped flag into
+ * the CURRENT session slot first (slot authority — shared with VS Code, per-session), then
+ * the config.json mirror (CLI visibility/compat; no longer the cross-session source of truth).
+ * The in-memory agent.config.agent.engineering (already flipped) stays the live authority for
+ * this process; saveSession also round-trips it on every turn-end write.
+ */
+async function persistEngineering(ctx, agent) {
+  const slot = activeSlot(agent.cwd)
+  try {
+    const p = slotPath(agent.cwd, slot)
+    const data = JSON.parse(readFileSync(p, "utf8"))
+    if (data && typeof data === "object" && Array.isArray(data.history)) {
+      data.engineering = agent.config.agent.engineering
+      writeSessionFile(p, data)
+    }
+  } catch { /* slot missing/unreadable — config mirror still written */ }
+  if (ctx.persistRaw) {
+    await ctx.persistRaw((raw) => {
+      raw.agent ??= {}
+      raw.agent.engineering = agent.config.agent.engineering
+    })
+  }
+}