duaer-spec 0.26.0 → 0.27.1

package/.duaer/specs/273-fde06-data-precheck/spec.md

@@ -0,0 +1,37 @@
+# Feature Specification: FDE-06 import precheck
+
+## Goal
+
+A feature confirm card cannot pass until it records a field mapping, an
+import precheck failure list, and that the list can be exported for
+cleanup. Kickoff schedules that precheck before implementation.
+
+## In scope
+
+- Local validate on dataPrecheck
+- One FDE-06 task per confirmed module that declares an import, placed
+  before that module's implement task and after the environment probe
+  when both exist
+- Hint, placeholder, and chat/accept prompts
+- Explicit opt-out: no import for this module
+
+## Out of scope
+
+- Bug desk
+- Scanning a customer database from the desk
+
+## Assumptions
+
+- The desk records the checklist; the digital employee produces the
+  mapping, the failure list, and the export.
+- 「本模块无导入」 / "no import" skips the three requirements and the
+  kickoff task.
+
+## Acceptance
+
+1. A vague line or a line missing mapping, failure list, or export fails
+   local validate
+2. All three present, or the no-import opt-out, passes
+3. Kickoff adds an FDE-06 data precheck before implement when an import
+   is declared, and skips it on the opt-out
+4. npm test and npm run test:live pass

package/.duaer/specs/273-fde06-data-precheck/tasks.md

@@ -0,0 +1,5 @@
+# Tasks — 273-fde06-data-precheck
+
+- [x] Validate the import precheck (mapping, failure list, export, or no-import opt-out)
+- [x] Inject an FDE-06 kickoff task before implement
+- [x] Update hints, prompts, docs, and tests

package/.duaer/specs/274-fde05-external-deps/delivery.json

@@ -0,0 +1,9 @@
+{
+  "status": "accepted",
+  "summary": "Feature confirm requires a blocker, SLA, backup mock, and parallel path, or a no-dependency opt-out. Kickoff schedules the board before implement.",
+  "verification": {
+    "L0": "node --check bin/duaer-live.mjs bin/live-modules.mjs web/live-dev/app.js web/live-dev/external-deps.mjs — pass",
+    "L1": "npm test — 250 pass",
+    "L3": "npm run test:live — pass"
+  }
+}

package/.duaer/specs/274-fde05-external-deps/spec.md

@@ -0,0 +1,37 @@
+# Feature Specification: FDE-05 external dependency board
+
+## Goal
+
+A feature confirm card cannot pass until it records a blocker, an SLA, a
+backup mock, and a parallel path for third-party, ERP, or SSO work.
+Kickoff schedules that board before implementation.
+
+## In scope
+
+- Local validate on externalDeps
+- One FDE-05 task per confirmed module that declares an external
+  dependency, placed before implement and after the env probe and data
+  precheck when those exist
+- Hint, placeholder, and chat/accept prompts
+- Explicit opt-out: no external dependency
+
+## Out of scope
+
+- Bug desk
+- Calling the vendor or the customer ERP from the desk
+
+## Assumptions
+
+- The desk records the board; the digital employee keeps the blocker,
+  SLA, mock, and parallel path current.
+- 「本模块无外部依赖」 / "no external dependency" skips the four items
+  and the kickoff task.
+
+## Acceptance
+
+1. A vague line or a line missing blocker, SLA, mock, or parallel path
+   fails local validate
+2. All four present, or the no-dependency opt-out, passes
+3. Kickoff adds an FDE-05 task before implement when a dependency is
+   declared, and skips it on the opt-out
+4. npm test and npm run test:live pass

package/.duaer/specs/274-fde05-external-deps/tasks.md

@@ -0,0 +1,5 @@
+# Tasks — 274-fde05-external-deps
+
+- [x] Validate the external dependency board (blocker, SLA, mock, parallel path, or opt-out)
+- [x] Inject an FDE-05 kickoff task before implement
+- [x] Update hints, prompts, docs, and tests

package/.duaer/specs/275-release-0271/spec.md

@@ -0,0 +1,13 @@
+# Feature Specification: Release 0.27.1
+
+## Goal
+
+Ship 0.27.1: FDE-03 environment checklist, FDE-04 compat evidence, FDE-05
+external dependency board, FDE-06 import precheck, and the patch-version
+policy. Promote develop to main, publish a GitHub Release, and let npm
+Trusted Publishing run.
+
+## Acceptance
+
+1. `package.json` is `0.27.1`; CHANGELOG has `0.27.1` and an empty Unreleased section.
+2. Tag `v0.27.1` is on `main`; GitHub Release is published.

package/.duaer/specs/275-release-0271/tasks.md

@@ -0,0 +1,4 @@
+# Tasks — 275-release-0271
+
+- [x] Bump 0.27.1 and move changelog notes
+- [ ] Tag v0.27.1 on main and publish the GitHub Release

package/AGENTS.md

@@ -294,7 +294,9 @@ After normal development:
 12. Push only when the user explicitly requested remote publishing for the
     current request
 13. Promote **`develop` → `main`** only when the user explicitly asks to ship /
-    go online (see [branching-and-release](docs/agent/branching-and-release.md))
+    go online (see [branching-and-release](docs/agent/branching-and-release.md)).
+    Fast iteration: bump the **patch** (`0.27.1`, `0.27.2`, …). Do not bump
+    the minor on every ship. The next release after `0.27.1` is `0.27.2`.
 
 **Production hotfix:** base and merge into **`main`**, then merge the fix into
 **`develop`** so integration does not regress. Then clean up the worktree.
@@ -350,7 +352,8 @@ git worktree prune
 13. Stop worktree services; remove worktree; delete short branch; **handoff**
     restart on `develop` (`duaer handoff [--run]` / `.duaer/handoff.json`)
 14. Push only when explicitly requested
-15. Promote **`develop` → `main`** only when the user explicitly asks to go online
+15. Promote **`develop` → `main`** only when the user explicitly asks to go online.
+    Version bump is the patch (`0.27.2` next); see branching-and-release.
 
 Development must not begin before isolation steps 1–3 are complete.
 

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 ## Unreleased
 
+## 0.27.1 — 2026-09-21
+
+### Feat: FDE-05 external dependency board before kickoff
+
+- Feature confirm requires a blocker, SLA, backup mock, and parallel path,
+  or an explicit no-dependency opt-out
+- Kickoff adds that board before implement when a third party, ERP, or SSO
+  is declared
+
+### Feat: FDE-06 import precheck before kickoff
+
+- Feature confirm requires a field mapping, an import failure list, and an
+  export for cleanup, or an explicit no-import opt-out
+- Kickoff adds a data-precheck task before implement when an import is
+  declared
+
+### Feat: FDE-03 environment checklist before kickoff
+
+- Feature confirm requires DNS, TLS, CORS, auth, and third-party reachability
+  recorded as passed, or an explicit no-customer opt-out
+- A failed probe blocks confirm
+- Kickoff adds an environment-probe task before implement when a customer
+  environment is declared
+
+### Feat: FDE-04 browser matrix must include evidence
+
+- Device matrix needs two named browsers or domestic clients, screenshot or
+  cloud evidence, and a polyfill or fallback
+- Kickoff adds a compat-evidence task per confirmed module
+
+### Docs: fast iteration uses patch versions
+
+- Default ship bump is the last number (`0.27.1`, `0.27.2`, …)
+- Next release after `0.27.0` is `0.27.1`; do not jump the minor on every ship
+
+## 0.27.0 — 2026-09-21
+
+### Feat: FDE-07 UAT pack on confirm
+
+- Feature exception cases must cover empty, failure, permission, timeout, and retry
+- A declared API contract also requires an error code or HTTP status in that text
+- Kickoff adds a UAT task per confirmed module
+
+### Fix: keep baseline confirm fields after desk refresh
+
+- Restoring a project session copies device matrix, critical paths, exception
+  cases, and API contract back onto the confirm card
+
+### Feat: FDE-02 API contract gate on confirm + kickoff tasks
+
+- Feature confirm requires `apiContract` (OpenAPI/types path or「本模块无 HTTP API」)
+- Kickoff injects contract sync / Mock / CI contract-test tasks when a path is declared
+- Deliverables and baseline fingerprint include the field
+
+### Fix: pass FDE-01 baseline fields through chat SSE
+
+- `parseChatResult` / `chatDoneSsePayload` keep deviceMatrix, criticalPaths,
+  exceptionCases so the middle confirm card fills from chat JSON
+
+### Fix: guide filling FDE-01 baseline confirm fields
+
+- Feature chat / accept / fix / revise prompts include device matrix, critical
+  paths, and exception cases (fill defaults or offer options — do not leave empty)
+- Confirm card placeholders show examples instead of bare「待确认」
+
+### Fix: auto-route architecture edges that cross unrelated nodes
+
+- Before Archify deliver, long same-row edges that would pass through other
+  components get a bottom `via` detour (`clean-flow/edge-through-node`)
+
+### Docs: README covers FDE-01 baseline sign
+
+- zh-CN / en README: feature confirm fields, signed baseline before kickoff,
+  change order, deliverables baseline history
+
+### Feat: FDE-01 signed scope + acceptance baseline before kickoff
+
+- Confirm card requires device matrix, critical paths, and exception cases (feature)
+- Dispatch requires a signed baseline (signer + fingerprint); change order clears sign and reopens confirm
+- Deliverables page shows baseline sign-off and change history
+
 ## 0.26.0 — 2026-09-20
 
 ### Fix: npm provenance repository URL after GitHub move

package/README.md

@@ -65,15 +65,17 @@ After install, these are the capabilities you actually use:
 A local web console (`duaer live`) for “chat → confirm → dispatch → watch → open result”:
 
 - **Projects.** Create and switch projects; each keeps its own chat and progress.
-- **Chat until the ask is clear.** Left chat; center confirm cards (goal / out of scope / checkable acceptance). Vague acceptance cannot be confirmed. Beside **Send**, tap **Record** to capture speech; with a **speech recognition (STT) model** in Settings (OpenAI-compatible `/audio/transcriptions`, e.g. whisper-1), the clip is decoded into the composer—edit, then send.
+- **Chat until the ask is clear.** Left chat; center confirm cards (goal / out of scope / checkable acceptance). Feature cards also need **device matrix, critical paths, and exception cases**. Vague acceptance cannot be confirmed. Beside **Send**, tap **Record** to capture speech; with a **speech recognition (STT) model** in Settings (OpenAI-compatible `/audio/transcriptions`, e.g. whisper-1), the clip is decoded into the composer—edit, then send.
 - **Split big work into modules.** Confirm module by module; nothing starts until you kick off after the ones you care about are confirmed.
 - **Architecture diagram.** After requirements, review the system diagram; click it for fullscreen; kickoff waits until architecture is confirmed. If chat claims the diagram is ready but the middle panel is empty, the same bubble offers Regenerate — it does not leave a false “ready” line.
+- **Sign the scope + acceptance baseline before kickoff.** After architecture confirm, an operator must **sign** (signer + time; fingerprint of confirmed module cards). Unsigned or stale fingerprints block **Write Brief and start**. An **open change** (with reason) clears the sign, returns modules for re-confirm, then architecture and re-sign.
 - **Dispatch digital employees to code.** Pick a product folder and Cursor Agent or Claude Code; work happens in an isolated worktree, not directly on your long-lived branches.
 - **Visible task progress.** Work is a checklist; each finished item is checked off and the console refreshes; dependent tasks release in waves so agents don’t pile on blocked work.
 - **Employee roles.** Top-bar **digital employee** directory (Implementer / Functional regression / Deployer). Optional parallel workers on the same CLI. See the next section.
 - **Locales.** Console UI: zh-CN, zh-TW, en, ja, ko, es, pt-BR, fr, de, ru, vi.
 - **Deliverables and results.** Open a deliverables page (requirements timeline,
-  architecture, tasks, delivery); when done, open the page or the project folder.
+  confirmation, baseline sign-off and change history, architecture, tasks,
+  delivery); when done, open the page or the project folder.
 - **Revise when it’s not right.** Continue in left chat → re-confirm → relaunch on
   the same job without starting from scratch. After deploy, **Revise again** and
   **Fix a bug** stay on the result bar.
@@ -163,15 +165,21 @@ mock LLM — no paid API).
    content. Messy multi-topic talk is fine: the console evolves **`modules[]`**
    (tabs). Chat bubbles render **Markdown** (`**bold**`, code, links).  
 2. Per module: fill the confirm card (goal / out-of-scope / **checkable**
-   acceptance / assumptions). Vague acceptance fails the gate; validate must
-   pass before **Confirm**. Confirming a module **locks that card only** — it
-   does **not** write a Brief or start workers yet. Jump between modules freely.  
+   acceptance / assumptions; feature cards also need **device matrix /
+   critical paths / exception cases**). Vague acceptance or missing baseline
+   fields fails the gate; validate must pass before **Confirm**. Confirming a
+   module **locks that card only** — it does **not** write a Brief or start
+   workers yet. Jump between modules freely.  
 3. When **all** modules you care about are confirmed → review / confirm
-   **architecture** (Archify) → **kickoff**. Kickoff writes the Brief, builds a
-   **dependency-aware task pool** (`dependsOn`), and assigns work. Default is
-   **1** worker; optionally **N** parallel workers on the **same CLI**. Shared
-   tasks go to worker 1; module tasks round-robin. Each worker gets its own
-   **Terminal queue lane** (`live-terminal` / `live-terminal/w2`…).  
+   **architecture** (Archify) → **sign the scope + acceptance baseline**
+   (signer) → **kickoff**. Kickoff stays blocked while unsigned or when the
+   fingerprint no longer matches confirmed cards. Kickoff writes the Brief,
+   builds a **dependency-aware task pool** (`dependsOn`), and assigns work.
+   Default is **1** worker; optionally **N** parallel workers on the **same
+   CLI**. Shared tasks go to worker 1; module tasks round-robin. Each worker
+   gets its own **Terminal queue lane** (`live-terminal` /
+   `live-terminal/w2`…). To change scope: **open change** (reason) → clear
+   sign and re-confirm modules → architecture again → re-sign.  
 4. Pick a product repo (browse / scan / recent), or paste a path / project name.
    Missing paths are created; set **Projects parent folder** so short names
    resolve under it. Non-git folders get `git init -b develop`; missing
@@ -184,10 +192,10 @@ mock LLM — no paid API).
    `.worktree/feat-*` and opens **Terminal** for each worker lane.  
 7. Progress shows a **next-action** stage strip, then `tasks.md` polling.
    **View deliverables** (above progress) opens a generated HTML page of stage
-   artifacts (requirements doc timeline, confirmation, architecture, task pool,
-   delivery). On delivery, workers update the product **README** before
-   `delivery.json` is `accepted`. Then open **Results** (**View result** when a
-   page exists, otherwise **Open
+   artifacts (requirements doc timeline, confirmation, baseline sign-off and
+   change history, architecture, task pool, delivery). On delivery, workers
+   update the product **README** before `delivery.json` is `accepted`. Then open
+   **Results** (**View result** when a page exists, otherwise **Open
    project folder**).  
 8. If the result is not right: **Continue improving (left chat)** → confirm the
    revise card (same validate gate) → re-confirm architecture (keep or redesign)

package/README.zh-CN.md

@@ -28,14 +28,15 @@
 本机开一个网页控制台（`duaer live`），专门管「从聊需求到派工、看进度、看结果」：
 
 - **项目管理。** 建项目、切换项目；每个项目自己的对话和进度，互不搅在一起。
-- **聊着把需求聊清楚。** 左边聊天；中间把目标、边界、验收写成确认卡；空话验收过不了，得能检查才给确认。发送旁可点 **录音**；在设置里配置 **语音识别模型**（兼容 OpenAI `/audio/transcriptions`，如 whisper-1）后，录完会解码成文字填入输入框，改完再发送。
+- **聊着把需求聊清楚。** 左边聊天；中间把目标、边界、验收写成确认卡；功能卡还要填 **浏览器/设备矩阵、关键路径、异常态**。空话验收过不了，得能检查才给确认。发送旁可点 **录音**；在设置里配置 **语音识别模型**（兼容 OpenAI `/audio/transcriptions`，如 whisper-1）后，录完会解码成文字填入输入框，改完再发送。
 - **大需求可拆成多个模块。** 一块一块确认，确认完一块不会立刻开工，全部谈妥再一起派。
 - **系统架构图。** 确认需求后一起看架构；点图可全屏查看；架构确认后才能派工。若对话称已生成但中间栏没有图，同一条气泡会改成提示并提供「重新生成架构图」，不会留下假的「已生成」。
+- **签署范围与验收基线再开工。** 架构确认后须签署（签字人 + 时间；指纹对上已确认模块卡）；未签或卡面改过不得「写入 Brief 并启动」。开 **变更单**（写原因）会清签、退回重确认，再架构、再签。
 - **一键派数字员工写代码。** 选产品目录、选 Cursor Agent 或 Claude Code，点开工；它在隔离目录里改代码，不直接乱动你的主分支。
 - **任务进度看得见。** 任务拆成一条条可勾选项；做完勾一项，控制台实时刷新；有依赖的任务会排队放行，不会一窝蜂乱做。
 - **数字员工分工。** 顶部有「数字员工」目录（实现 / 功能回归 / 部署）；可开多个并行（同一套 CLI）。详见下一节。
 - **中 / 繁中 / 英 / 日 / 韩 / 西 / 葡 / 法 / 德 / 俄 / 越界面。** 控制台文案可切换语种。
-- **看交付物和结果。** 可打开交付物页（需求时间线、架构、任务、交付记录）；做完了可打开页面或项目文件夹。
+- **看交付物和结果。** 可打开交付物页（需求时间线、确认书、基线签署与变更记录、架构、任务、交付）；做完了可打开页面或项目文件夹。
 - **不满意就继续改。** 左侧继续聊改进 → 再确认 → 同一次任务上续派，不用从头建仓。部署后结果栏仍可「再改一版」和「修 bug」。
 - **修 bug。** 走缺陷卡（不拆多模块），默认跳过架构，短任务池，开 `fix/` 分支（可选从 `main` 出紧急修复）。交付过的地址/启动信息会自动带入；缺陷和迭代排在同一条项目时间线上。
 - **快速导航。** 对话栏右缘「导航」可跳到：对话底部 · 确认卡 · 结果 · 进度。
@@ -145,15 +146,15 @@ duaer live config --base-url https://api.openai.com/v1 --api-key sk-... --model
 **流程**
 
 1. 打开或新建**项目**，再聊天。右上角「项目」列表会显示每个项目的**交付状态**；有内容时可直接打开**交付物**。话题可以乱跳：控制台会演进 **`modules[]`**（模块页签）。气泡支持 **Markdown**（加粗、代码、链接）。  
-2. **按模块**填确认卡（目标 / 不做 / **可检查验收** / 假设）。空泛验收过不了门禁；须校验通过才能点确认。确认只**锁住该模块卡**，**不会**立刻写 Brief 或开工。模块之间可随时切换。  
-3. 关心的模块都确认完 → 审 / 确认**架构**（Archify）→ **开工（kickoff）**。开工才写 Brief，建带 **`dependsOn` 的任务池**，并分派。默认 **1** 个数字员工；可选 **N** 个同 CLI 并行。共享任务给 1 号；模块任务轮询。每个 worker 独占一条 **Terminal 队列泳道**（`live-terminal` / `live-terminal/w2`…）。  
+2. **按模块**填确认卡（目标 / 不做 / **可检查验收** / 假设；功能卡另填 **设备矩阵 / 关键路径 / 异常态**）。空泛验收或缺基线字段过不了门禁；须校验通过才能点确认。确认只**锁住该模块卡**，**不会**立刻写 Brief 或开工。模块之间可随时切换。  
+3. 关心的模块都确认完 → 审 / 确认**架构**（Archify）→ **签署范围与验收基线**（签字人）→ **开工（kickoff）**。未签或指纹与已确认卡不一致时开工按钮不可用。开工才写 Brief，建带 **`dependsOn` 的任务池**，并分派。默认 **1** 个数字员工；可选 **N** 个同 CLI 并行。共享任务给 1 号；模块任务轮询。每个 worker 独占一条 **Terminal 队列泳道**（`live-terminal` / `live-terminal/w2`…）。范围要改：开 **变更单**（写原因）→ 清签并退回模块重确认 → 再架构、再签。  
 4. 浏览 / 扫描 / 点选产品仓，或粘贴路径 / 项目名。路径不存在会自动创建；可先设**产品父目录**，再填短名在其下新建。非 git 目录会 `git init -b develop`；没有 develop/main/master 会建本地 `develop`。  
 5. 只选 **CLI 数字员工**：**Cursor Agent** 或 **Claude Code**  
    - Cursor：`curl https://cursor.com/install -fsS | bash`  
    - Claude Code：`npm install -g @anthropic-ai/claude-code`（或 `curl -fsSL https://claude.ai/install.sh | bash`）  
    - 要用 **DeepSeek 等其它模型**写代码：把 Claude Code 接到对应 API，见 [`docs/agent/worker-models.zh-CN.md`](docs/agent/worker-models.zh-CN.md)。FDE「配置模型」页下方也有同样说明。  
 6. 编辑「启动命令」（须以 `Duaer` 开头）→ 开工建 `.worktree/feat-*`，并为每条 worker 泳道打开 **Terminal**。  
-7. 右侧进度列先提示**下一步**（阶段条），并轮询 `tasks.md`。进度上方 **查看交付物** 会打开生成的 HTML 页（需求文档时间线、确认书、架构、任务池、交付等）。交付时数字员工先更新产品仓 **README**，再把 `delivery.json` 标为 `accepted`。然后出现 **结果**（有页面时 **查看结果**；否则 **打开项目目录**）。  
+7. 右侧进度列先提示**下一步**（阶段条），并轮询 `tasks.md`。进度上方 **查看交付物** 会打开生成的 HTML 页（需求文档时间线、确认书、基线签署与变更、架构、任务池、交付等）。交付时数字员工先更新产品仓 **README**，再把 `delivery.json` 标为 `accepted`。然后出现 **结果**（有页面时 **查看结果**；否则 **打开项目目录**）。  
 8. 成品不满意：点 **继续改进（左侧对话）** → 确认改进卡（同样须校验）→ 再确认架构（保留或重画）→ 同 worktree 续派（先清残留 Agent 再入队）。进度跟本轮 `R{n}-*`。启动失败会回滚本轮 Brief Revision；状态行按泳道显示 Terminal 忙闲/队列。  
 9. 若需要上线 / 公网：在控制台选 **计划托管平台**（Cloudflare / 阿里云 / AWS / GitHub Pages），说明见 [`docs/agent/deploy-targets.md`](docs/agent/deploy-targets.md)。未指定时默认 **GitHub CLI（`gh`）+ Actions**（[`docs/agent/deploy-github.md`](docs/agent/deploy-github.md)）