duaer-spec 0.27.0 → 0.27.2

package/.claude/rules/agents-workflow.md

@@ -50,6 +50,8 @@ cd .worktree/feat-login
 - Push only when the user explicitly asks (a deploy/hosting ask authorizes
   the `gh` + push needed for that publish — see `docs/agent/deploy-github.md`)
 - Promote **`develop` → `main`** only when the user asks to go online
+- Version: fast iteration bumps the **patch** (`0.27.1`, `0.27.2`, …). Next
+  after `0.27.1` is `0.27.2`. Do not bump the minor on every ship.
 - English docs: no Chinese (CJK); Chinese docs may include English terms
 
 ## GitHub issue / PR intake

package/.claude/rules/duaer-spec.md

@@ -33,6 +33,7 @@ For new behavior, fixes, refactors that change product behavior, or architecture
    as you go so progress is visible. Do not leave only coarse mega-tasks.
 7. Merge to **`develop`** when done (hotfix: **`main`**, then back-merge
    **`develop`**). Promote to **`main`** only if the user asks to go online.
+   Version bump is the patch (`0.27.2` next).
 8. **Handoff (mandatory):** stop processes bound to `.worktree/<id>/`, remove
    the worktree, then restart services from the primary checkout on `develop`
    using `.duaer/handoff.json` / `duaer handoff [--run]`. Never leave the user

package/.cursor/rules/agents-workflow.mdc

@@ -53,6 +53,8 @@ cd .worktree/feat-login
 - Push only when the user explicitly asks (a deploy/hosting ask authorizes
   the `gh` + push needed for that publish — see `docs/agent/deploy-github.md`)
 - Promote **`develop` → `main`** only when the user asks to go online
+- Version: fast iteration bumps the **patch** (`0.27.1`, `0.27.2`, …). Next
+  after `0.27.1` is `0.27.2`. Do not bump the minor on every ship.
 - English docs: no Chinese (CJK); Chinese docs may include English terms
 
 ## GitHub issue / PR intake

package/.cursor/rules/duaer-spec.mdc

@@ -37,6 +37,7 @@ For new behavior, fixes, refactors that change product behavior, or architecture
    as you go so progress is visible. Do not leave only coarse mega-tasks.
 7. Merge to **`develop`** when done (hotfix: **`main`**, then back-merge
    **`develop`**). Promote to **`main`** only if the user asks to go online.
+   Version bump is the patch (`0.27.2` next).
 8. **Handoff (mandatory):** stop processes bound to `.worktree/<id>/`, remove
    the worktree, then restart services from the primary checkout on `develop`
    using `.duaer/handoff.json` / `duaer handoff [--run]`. Never leave the user

package/.duaer/active-job.json

@@ -1,5 +1,5 @@
 {
-  "feature": "269-release-027",
-  "branch": "chore/release-027",
-  "worktree": ".worktree/chore-release-027"
+  "feature": "281-release-0272",
+  "branch": "feat/release-0272",
+  "worktree": ".worktree/feat-release-0272"
 }

package/.duaer/specs/270-patch-version/delivery.json

@@ -0,0 +1,7 @@
+{
+  "status": "accepted",
+  "summary": "Fast iteration ships as patch versions. Next release after 0.27.0 is 0.27.1.",
+  "verification": {
+    "docs": "Policy only; no runtime change. testing.md docs waiver."
+  }
+}

package/.duaer/specs/270-patch-version/spec.md

@@ -0,0 +1,19 @@
+# Feature Specification: Patch versions for fast iteration
+
+## Goal
+
+Ships after 0.27.0 increment the patch number. The next release is 0.27.1.
+
+## In scope
+
+- Release docs and agent rules state the default bump is the last number
+
+## Out of scope
+
+- Cutting 0.27.1 now
+- Changing npm or GitHub release automation
+
+## Acceptance
+
+1. Branching docs say 0.27.0 is followed by 0.27.1, not 0.28.0
+2. Agent rules repeat that patch bump

package/.duaer/specs/270-patch-version/tasks.md

@@ -0,0 +1,4 @@
+# Tasks — 270-patch-version
+
+- [x] Document patch bumps (next release 0.27.1)
+- [x] Repeat the rule in agent workflow files

package/.duaer/specs/271-fde04-compat/delivery.json

@@ -0,0 +1,9 @@
+{
+  "status": "accepted",
+  "summary": "Feature device matrix must name two targets, evidence, and a fallback; kickoff schedules the compat check.",
+  "verification": {
+    "L0": "node --check bin/duaer-live.mjs bin/live-modules.mjs — pass",
+    "L1": "npm test — 239 pass",
+    "L3": "npm run test:live — pass"
+  }
+}

package/.duaer/specs/271-fde04-compat/spec.md

@@ -0,0 +1,25 @@
+# Feature Specification: FDE-04 browser matrix evidence
+
+## Goal
+
+A feature confirm card cannot pass with a vague browser line. The device
+matrix must name real targets, point at evidence, and state a fallback.
+Kickoff schedules that check.
+
+## In scope
+
+- Local validate on deviceMatrix
+- One FDE-04 task per confirmed module
+- Hint, placeholder, and chat/accept prompts
+
+## Out of scope
+
+- Bug desk
+- Running a device lab
+
+## Acceptance
+
+1. "主流浏览器" or a single browser name fails local validate
+2. Two named targets plus screenshot/cloud evidence plus a fallback passes
+3. Kickoff adds an FDE-04 compat evidence task
+4. npm test and npm run test:live pass

package/.duaer/specs/271-fde04-compat/tasks.md

@@ -0,0 +1,5 @@
+# Tasks — 271-fde04-compat
+
+- [x] Validate the browser matrix as evidence
+- [x] Inject an FDE-04 kickoff task
+- [x] Update hints, prompts, docs, and tests

package/.duaer/specs/272-fde03-env-check/delivery.json

@@ -0,0 +1,9 @@
+{
+  "status": "accepted",
+  "summary": "Feature confirm requires a passed DNS/TLS/CORS/auth/third-party checklist, or a no-customer opt-out. Kickoff schedules the probe before implement.",
+  "verification": {
+    "L0": "node --check bin/duaer-live.mjs bin/live-modules.mjs web/live-dev/app.js web/live-dev/env-check.mjs — pass",
+    "L1": "npm test — 242 pass",
+    "L3": "npm run test:live — pass"
+  }
+}

package/.duaer/specs/272-fde03-env-check/spec.md

@@ -0,0 +1,34 @@
+# Feature Specification: FDE-03 environment checklist
+
+## Goal
+
+A feature confirm card cannot pass until the environment checklist records
+DNS, TLS, CORS, auth, and third-party reachability as passed. A failed probe
+blocks confirm. Kickoff schedules that probe before implementation.
+
+## In scope
+
+- Local validate on envChecklist
+- One FDE-03 task per confirmed module that declares a customer environment,
+  placed before that module's implement task
+- Hint, placeholder, and chat/accept prompts
+- Explicit opt-out: no customer environment
+
+## Out of scope
+
+- Bug desk
+- Scanning the customer network from the desk
+
+## Assumptions
+
+- The desk records the checklist; the digital employee runs the probes.
+- 「无客户联调环境」 / "no customer environment" skips the five probes and
+  the kickoff task.
+
+## Acceptance
+
+1. A vague line, a missing probe, or any failed probe fails local validate
+2. All five probes marked passed, or the no-customer opt-out, passes
+3. Kickoff adds an FDE-03 env probe before implement when a customer
+   environment is declared, and skips it on the opt-out
+4. npm test and npm run test:live pass

package/.duaer/specs/272-fde03-env-check/tasks.md

@@ -0,0 +1,5 @@
+# Tasks — 272-fde03-env-check
+
+- [x] Validate the environment checklist (five probes passed, or no-customer opt-out)
+- [x] Inject an FDE-03 kickoff task before implement
+- [x] Update hints, prompts, docs, and tests

package/.duaer/specs/273-fde06-data-precheck/delivery.json

@@ -0,0 +1,9 @@
+{
+  "status": "accepted",
+  "summary": "Feature confirm requires a field mapping, an import failure list, and an export, or a no-import opt-out. Kickoff schedules the precheck before implement.",
+  "verification": {
+    "L0": "node --check bin/duaer-live.mjs bin/live-modules.mjs web/live-dev/app.js web/live-dev/data-precheck.mjs — pass",
+    "L1": "npm test — 246 pass",
+    "L3": "npm run test:live — pass"
+  }
+}

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/delivery.json

@@ -0,0 +1,9 @@
+{
+  "status": "accepted",
+  "summary": "0.27.1 is on main as v0.27.1, GitHub Release published, npm Trusted Publishing succeeded.",
+  "verification": {
+    "publish": "git push origin main develop v0.27.1 — fast-forward 1d6d164..26ede20",
+    "release": "https://github.com/Duaer/duaer-spec/releases/tag/v0.27.1",
+    "npm": "gh run 35558574069 success — + duaer-spec@0.27.1"
+  }
+}

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
+- [x] Tag v0.27.1 on main and publish the GitHub Release

package/.duaer/specs/276-fde08-perf-budget/delivery.json

@@ -0,0 +1,9 @@
+{
+  "status": "accepted",
+  "summary": "Feature confirm requires LCP, INP, bundle size, virtualized long lists, a weak-network check, and a large-data check, or a no-page-performance opt-out. A vague speed line fails. Kickoff schedules the budget before implement.",
+  "verification": {
+    "L0": "node --check bin/duaer-live.mjs bin/live-modules.mjs web/live-dev/app.js web/live-dev/perf-budget.mjs — pass",
+    "L1": "npm test — 254 pass",
+    "L3": "npm run test:live — pass"
+  }
+}

package/.duaer/specs/276-fde08-perf-budget/spec.md

@@ -0,0 +1,38 @@
+# Feature Specification: FDE-08 performance budget
+
+## Goal
+
+A feature confirm card cannot pass on a vague speed claim. It must record
+LCP, INP, bundle size, virtualized long lists, a weak-network check, and a
+large-data check. Kickoff schedules that budget before implementation.
+
+## In scope
+
+- Local validate on perfBudget
+- One FDE-08 task per confirmed module that declares page performance,
+  placed before implement and after the env probe, data precheck, and
+  external-dependency board when those exist
+- Hint, placeholder, and chat/accept prompts
+- Explicit opt-out: no page performance requirement
+
+## Out of scope
+
+- Bug desk
+- Running a customer performance lab from the desk
+
+## Assumptions
+
+- The desk records the budget; the digital employee runs the weak-network
+  and large-data checks.
+- 「本模块无页面性能要求」 / "no page performance" skips the six items
+  and the kickoff task.
+- "挺快的" and other vague speed lines fail.
+
+## Acceptance
+
+1. A vague speed line, or a line missing any of the six items, fails
+   local validate
+2. All six present, or the no-page-performance opt-out, passes
+3. Kickoff adds an FDE-08 task before implement when page performance is
+   declared, and skips it on the opt-out
+4. npm test and npm run test:live pass

package/.duaer/specs/276-fde08-perf-budget/tasks.md

@@ -0,0 +1,5 @@
+# Tasks — 276-fde08-perf-budget
+
+- [x] Validate the performance budget (LCP, INP, bundle, long list, weak network, large data, or opt-out)
+- [x] Inject an FDE-08 kickoff task before implement
+- [x] Update hints, prompts, docs, and tests

package/.duaer/specs/277-project-dir-reuse/delivery.json

@@ -0,0 +1,9 @@
+{
+  "status": "accepted",
+  "summary": "Create mode refuses when the target project directory already exists. Open from the list or browse still works. Existing folder contents are left untouched.",
+  "verification": {
+    "L0": "node --check bin/live-repo-path.mjs bin/duaer-live.mjs web/live-dev/app.js — pass",
+    "L1": "npm test — pass",
+    "L3": "npm run test:live — pass"
+  }
+}

package/.duaer/specs/277-project-dir-reuse/spec.md

@@ -0,0 +1,31 @@
+# Feature Specification: Refuse reusing an existing project directory on create
+
+## Goal
+
+Creating a new project must not reuse a directory that already exists.
+An existing folder can only be opened from the project list or by browse-open.
+
+## In scope
+
+- `/api/projects/activate` create mode refuses when the target path already exists
+- Create form sends create mode; list click opens without create
+- Clear Chinese error telling the user to rename or open the existing project
+- Unit / smoke coverage
+
+## Out of scope
+
+- Deleting or renaming old project folders
+- Changing how desk sessions are keyed
+
+## Assumptions
+
+- "选为当前项目" on the create form means create when the path is new
+- Clicking an item under 「已有项目」 means open
+- Browse into an existing folder opens it; it does not create over it
+
+## Acceptance
+
+1. Create with a folder name that already exists under the parent returns an error; disk contents are unchanged
+2. Opening the same path from the project list still works
+3. Create with a never-used name still creates the directory
+4. `npm test` and `npm run test:live` pass

package/.duaer/specs/277-project-dir-reuse/tasks.md

@@ -0,0 +1,5 @@
+# Tasks — 277-project-dir-reuse
+
+- [x] Refuse create when the target project directory already exists
+- [x] Keep open-from-list / browse-open working for existing paths
+- [x] Add tests, copy, and E2E row

package/.duaer/specs/278-project-create-unique/delivery.json

@@ -0,0 +1,9 @@
+{
+  "status": "accepted",
+  "summary": "Create uses only a short folder name under the product parent. Absolute paths, existing folders, and duplicate project titles are refused. Open from the list or browse still works.",
+  "verification": {
+    "L0": "node --check bin/live-repo-path.mjs bin/duaer-live.mjs — pass",
+    "L1": "npm test — pass",
+    "L3": "npm run test:live — pass"
+  }
+}

package/.duaer/specs/278-project-create-unique/spec.md

@@ -0,0 +1,27 @@
+# Feature Specification: Unique create — short name under parent only
+
+## Goal
+
+Create and open are separate. Creating a project only uses a short folder
+name under the product parent. Absolute paths, duplicate folders, and
+duplicate project titles are refused.
+
+## In scope
+
+- Create mode: short name only, must have parent set, refuse if folder exists
+- Create mode: refuse if an existing project already uses that path or title
+- Open from list / browse still accepts absolute paths
+- Copy and labels match the rule
+
+## Out of scope
+
+- Moving or renaming existing project folders on disk
+- Deleting stale list entries
+
+## Acceptance
+
+1. Create with `/Users/.../pcdemo` fails; asks for a short name under the parent
+2. Create with a short name that already exists on disk or in the project list fails
+3. Create with a title already used by another project fails
+4. Open from the list still works with absolute paths
+5. `npm test` and `npm run test:live` pass

package/.duaer/specs/278-project-create-unique/tasks.md

@@ -0,0 +1,5 @@
+# Tasks — 278-project-create-unique
+
+- [x] Create resolves only a short name under the product parent
+- [x] Refuse duplicate folder and duplicate project title on create
+- [x] Update labels, hints, and tests

package/.duaer/specs/279-arch-side-detour/delivery.json

@@ -0,0 +1,8 @@
+{
+  "status": "accepted",
+  "summary": "Corridor-aware Archify edge detours (validated bottom/top/side/gutter) plus vertical labelAt so stacked clean-flow IR renders.",
+  "verification": {
+    "commands": ["node --test test/live-archify.test.mjs"],
+    "result": "16 pass / 0 fail"
+  }
+}

package/.duaer/specs/279-arch-side-detour/spec.md

@@ -0,0 +1,28 @@
+# Feature Specification: Architecture corridor detour for clean-flow
+
+## Goal
+
+When Archify rejects edges that cross unrelated components, auto-routing
+must pick a corridor whose segments stay clear of other boxes — not a
+naive bottom exit through column neighbors, and not a side via whose
+horizontal leg clips co-row nodes. Vertical edge labels must sit in the
+gap between stacked boxes.
+
+## In scope
+
+- `routeCrossingEdges` validates candidate routes (bottom/top wrap, side
+  corridor, gutter wrap) and applies the first clear detour
+- Re-route edges that already have a bad bottom via
+- Vertical edge labels get `labelAt` in the inter-box gap
+- Regression test matching the speaker/editor/store failure
+
+## Out of scope
+
+- Changing Archify itself
+- Full force-directed relayout
+
+## Acceptance
+
+1. The reproduced IR (speaker→editor, store→gen, 初稿/定稿 labels) renders
+2. Existing same-row reverse-edge test still passes
+3. `npm test` live-archify tests pass

package/.duaer/specs/279-arch-side-detour/tasks.md

@@ -0,0 +1,5 @@
+# Tasks — 279-arch-side-detour
+
+- [x] Corridor-aware detour for edges that cross unrelated components
+- [x] Place vertical edge labels in the gap (`labelAt`)
+- [x] Regression test + docs

package/.duaer/specs/280-arch-bottom-via-label/delivery.json

@@ -0,0 +1,8 @@
+{
+  "status": "accepted",
+  "summary": "Bottom/top via edge labels pin labelAt on the via corridor so 改稿 no longer overlaps artifact.",
+  "verification": {
+    "commands": ["node --check bin/live-archify.mjs", "node --test test/live-archify.test.mjs"],
+    "result": "17 pass / 0 fail"
+  }
+}

package/.duaer/specs/280-arch-bottom-via-label/spec.md

@@ -0,0 +1,22 @@
+# Feature Specification: Bottom-via edge labels clear mid-row boxes
+
+## Goal
+
+When a same-row edge detours under the floor, its label must stay on the
+via (below) — not be pulled up with `labelDy: -36` onto mid-row components
+such as `artifact`.
+
+## In scope
+
+- `repairEdgeLabelPlacement` pins `labelAt` under bottom vias / above top vias
+- Overlap nudge when an offset mid still hits a box
+- Regression for speaker→revise「改稿」 overlapping artifact
+
+## Out of scope
+
+- Changing Archify itself
+
+## Acceptance
+
+1. Reproduced IR renders via Archify
+2. `node --test test/live-archify.test.mjs` passes

package/.duaer/specs/280-arch-bottom-via-label/tasks.md

@@ -0,0 +1,5 @@
+# Tasks — 280-arch-bottom-via-label
+
+- [x] Pin bottom/top via labels with labelAt on the via corridor
+- [x] Regression test for 改稿 / artifact overlap
+- [x] Docs + delivery stamp

package/.duaer/specs/281-release-0272/spec.md

@@ -0,0 +1,13 @@
+# Feature Specification: Release 0.27.2
+
+## Goal
+
+Ship 0.27.2: architecture clean-flow corridor detours, bottom-via label
+placement, unique project create paths, and FDE-08 performance budget.
+Promote develop to main, publish a GitHub Release, and let npm Trusted
+Publishing run.
+
+## Acceptance
+
+1. `package.json` is `0.27.2`; CHANGELOG has `0.27.2` and an empty Unreleased section.
+2. Tag `v0.27.2` is on `main`; GitHub Release is published.

package/.duaer/specs/281-release-0272/tasks.md

@@ -0,0 +1,4 @@
+# Tasks — 281-release-0272
+
+- [x] Bump package.json to 0.27.2 and move CHANGELOG Unreleased
+- [ ] Promote develop → main, tag, 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.