@nanobpm/nano-workforce 0.70.2 → 0.72.0

package/app/userTasks.ts

@@ -0,0 +1,217 @@
+// Unified "Tasks" inbox read-model (issue #236) — the schema-driven pages' single source for the
+// Tasks page, listing EVERY open native user-task escalation awaiting a human decision so an operator
+// can resolve one in the nwf UI (Urban's `taskInbox` at /tasks is a read-only stub).
+//
+// The four migrated escalations (ADR 0046) are native `userTask`s with linked `.form`s. Their
+// completable keys were only ever denormalised for the FEATURE kinds (migrations 031/032, onto
+// `feature_runs`); the epic/PR kinds (`plan-review-decision`, `trial-merge-decision`, the PR
+// `wait-answer`) had no app-side pointer, so the pages could not drive a completion. This module owns
+// the `user_tasks` read-model row shape and the PURE derivation the `pollUserTasks` reconcile
+// (app/service.ts) projects: `buildUserTaskRow` (one open task → a desired row) and
+// `reconcileUserTasks` (the desired set vs the persisted set → the minimal upserts + deletes). The
+// engine iteration + writes live in the poller; the decisions live here so they are unit-testable
+// without a host, mirroring `deriveFeatureEscalationPatch`.
+//
+// Completion is NOT owned here — the page posts the typed form variables to the ONE canonical human
+// completer (`completeEscalationAsHuman`, app/agentCompletion.ts) / the existing feature answer &
+// acknowledge operations, the exact resume path the task inbox uses. This module only makes the open
+// tasks visible; a completed task's row is removed on the next pass when the engine no longer reports
+// it open.
+import type { DataLayer } from "@nanobpm/urban";
+import { FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT } from "./feature.ts";
+import type { PlanReview } from "./plan.ts";
+import type { TrialMergeAuditRow } from "./trialMerge.ts";
+
+const now = () => new Date().toISOString();
+
+/** The plan-review cap escalation user task (plan-fanout.bpmn) — a human directive (proceed/revise)
+ *  when the adversarial review loop exhausts its budget without approval. */
+export const PLAN_REVIEW_ELEMENT = "plan-review-decision";
+
+/** The trial-merge escalation user task (plan-fanout.bpmn) — a human decision (proceed/rebase/abandon)
+ *  when a wave's trial merge comes back red. */
+export const TRIAL_MERGE_ELEMENT = "trial-merge-decision";
+
+/** The PR review-loop escalation user task (convergence-loop.bpmn) — a human answer that resumes the
+ *  review loop and is handed to the next round. */
+export const PR_WAIT_ANSWER_ELEMENT = "wait-answer";
+
+/** One row per currently-open native user-task escalation, denormalised for the Tasks page. Keyed on
+ *  the completable `user_task_key` (a task is open at most once). Present iff the engine reports the
+ *  task open; `pollUserTasks` deletes it once the task is gone. */
+export interface UserTaskRow {
+  user_task_key: string;
+  element_id: string;
+  kind_label: string;
+  subject_type: string;
+  subject_key: string;
+  subject_url: string | null;
+  question: string | null;
+  process_key: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export const userTasks = (data: DataLayer) => data.table<UserTaskRow>("user_tasks", "user_task_key");
+
+/** Human-readable label per escalation element. The set of keys is the closed set of user-task
+ *  elements the Tasks inbox surfaces — an element absent from here is not an escalation and is
+ *  ignored by `buildUserTaskRow`, so an arbitrary internal user task can never leak into the inbox. */
+export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
+  [FEATURE_ESCALATION_ELEMENT]: "Feature escalation",
+  [FEATURE_BLOCKED_ELEMENT]: "Blocked feature run",
+  [PLAN_REVIEW_ELEMENT]: "Plan review",
+  [TRIAL_MERGE_ELEMENT]: "Trial merge",
+  [PR_WAIT_ANSWER_ELEMENT]: "PR review",
+};
+
+/** The denormalised context the poller has resolved for an open escalation user task. */
+export interface UserTaskContext {
+  userTaskKey: string;
+  elementId: string;
+  subjectType: "feature" | "plan" | "pr";
+  subjectKey: string;
+  subjectUrl?: string | null;
+  question?: string | null;
+  processKey?: string | null;
+}
+
+/** Pure: turn one resolved open escalation task into its desired read-model row, or `null` when the
+ *  element is not one of the surfaced escalation kinds (so a non-escalation user task is never listed)
+ *  or the required keys are blank. `created_at`/`updated_at` default to now for a fresh row; the
+ *  reconcile preserves the original `created_at` on an update. */
+export function buildUserTaskRow(ctx: UserTaskContext, at: string = now()): UserTaskRow | null {
+  const userTaskKey = ctx.userTaskKey.trim();
+  const subjectKey = ctx.subjectKey.trim();
+  const kindLabel = USER_TASK_KIND_LABELS[ctx.elementId];
+  if (!userTaskKey || !subjectKey || !kindLabel) return null;
+  const question = typeof ctx.question === "string" && ctx.question.trim() ? ctx.question.trim() : null;
+  return {
+    user_task_key: userTaskKey,
+    element_id: ctx.elementId,
+    kind_label: kindLabel,
+    subject_type: ctx.subjectType,
+    subject_key: subjectKey,
+    subject_url: ctx.subjectUrl ?? null,
+    question,
+    process_key: ctx.processKey ?? null,
+    created_at: at,
+    updated_at: at,
+  };
+}
+
+/** The minimal write plan a reconcile pass applies: rows to insert, rows to update in place (the
+ *  task is still open but its denormalised context changed), and keys to delete (the task is gone). */
+export interface UserTaskReconcile {
+  inserts: UserTaskRow[];
+  updates: UserTaskRow[];
+  deletes: string[];
+}
+
+/** True when the persisted row already matches the freshly-derived one on every display field, so the
+ *  reconcile can skip a no-op write (an update touches `updated_at`, which would otherwise churn the
+ *  row on every pass). `created_at`/`updated_at` are intentionally excluded. */
+function sameRow(a: UserTaskRow, b: UserTaskRow): boolean {
+  return (
+    a.element_id === b.element_id &&
+    a.kind_label === b.kind_label &&
+    a.subject_type === b.subject_type &&
+    a.subject_key === b.subject_key &&
+    a.subject_url === b.subject_url &&
+    a.question === b.question &&
+    a.process_key === b.process_key
+  );
+}
+
+/** Pure source of truth for the `pollUserTasks` reconcile: diff the DESIRED open-task rows (derived
+ *  from the engine this pass) against the PERSISTED rows, returning the minimal insert/update/delete
+ *  plan. A desired row not yet persisted is an insert; a persisted row whose task is still desired but
+ *  whose context drifted is an update (preserving its original `created_at`); a persisted row no longer
+ *  desired is a delete (its task was completed — here, via the inbox, or out-of-band). Idempotent: a
+ *  steady state with no drift yields empty lists, so the poller performs zero writes. */
+export function reconcileUserTasks(persisted: UserTaskRow[], desired: UserTaskRow[]): UserTaskReconcile {
+  const persistedByKey = new Map(persisted.map((r) => [r.user_task_key, r]));
+  const desiredByKey = new Map(desired.map((r) => [r.user_task_key, r]));
+  const inserts: UserTaskRow[] = [];
+  const updates: UserTaskRow[] = [];
+  const deletes: string[] = [];
+
+  for (const row of desired) {
+    const existing = persistedByKey.get(row.user_task_key);
+    if (!existing) {
+      inserts.push(row);
+    } else if (!sameRow(existing, row)) {
+      updates.push({ ...row, created_at: existing.created_at });
+    }
+  }
+  for (const row of persisted) {
+    if (!desiredByKey.has(row.user_task_key)) deletes.push(row.user_task_key);
+  }
+  return { inserts, updates, deletes };
+}
+
+// ── Audit-table accessors + derivations used by the poller to enrich the question text ────────────
+// These read the question/findings each escalation kind already records in a SURVIVING audit table,
+// keyed by the subject, so the Tasks grid can show WHAT is being decided. They are display-only.
+//
+// NB: the bespoke `plan_escalations` / `plan_review_escalations` mirror tables were retired in
+// migration 027 (the CONTRACT phase of the native-userTask migration), so the enrichment is derived
+// from the canonical append-only audit logs that DID survive — `plan_reviews` (the adversarial
+// plan-review log) and `plan_trial_merges` (the D3 trial-merge gate log) — not from a dropped mirror.
+// The PR-loop `escalations` audit table was deliberately KEPT by 027, so `prEscalations` still reads it.
+
+/** Pure: the findings that drove the still-open `plan-review-decision` escalation — the latest
+ *  adversarial plan-review round's critique. `plan_reviews` is append-only per (epoch, round); the
+ *  parked escalation is the tail of the current epoch, so the latest round by (epoch, round) carries
+ *  the rejecting findings the human is being asked to overrule. `null` when there is no round yet. */
+export function latestPlanReviewFindings(reviews: readonly PlanReview[]): string | null {
+  let latest: PlanReview | undefined;
+  for (const r of reviews) {
+    if (!latest || r.epoch > latest.epoch || (r.epoch === latest.epoch && r.round > latest.round)) latest = r;
+  }
+  return latest?.findings ?? null;
+}
+
+/** Pure: the summary that drove the still-open `trial-merge-decision` escalation — the newest
+ *  UNRESOLVED red trial-merge attempt. `plan_trial_merges` is append-only and supersede-on-insert
+ *  marks superseded rows `resolved = 1`, so the newest unresolved `suite-failed`/`merge-conflict` row
+ *  (highest `id`) is the wave awaiting the human decision. `null` when none is open. */
+export function latestTrialMergeQuestion(audits: readonly TrialMergeAuditRow[]): string | null {
+  let latest: TrialMergeAuditRow | undefined;
+  for (const a of audits) {
+    if (a.resolved === 1) continue;
+    if (a.result !== "suite-failed" && a.result !== "merge-conflict") continue;
+    if (!latest || a.id > latest.id) latest = a;
+  }
+  return latest?.summary ?? null;
+}
+
+/** One PR review-loop escalation (001_init.sql `escalations`). `status` is open | answered; the poller
+ *  reads the OPEN row's `question`. */
+export interface PrEscalationRow {
+  id: number;
+  pr_key: string;
+  round_no: number;
+  kind: string;
+  question: string;
+  answer: string | null;
+  status: string;
+  asked_at: string;
+  answered_at: string | null;
+}
+
+export const prEscalations = (data: DataLayer) =>
+  data.table<PrEscalationRow>("escalations", "id");
+
+/** Pure: the question for the still-open PR review-loop escalation. `escalations` is append-only and
+ *  `id` is an AUTOINCREMENT PK, so when a PR has multiple `open` rows the newest (highest `id`) is the
+ *  live one the human is being asked; a positional `[0]` from an unordered `find` could surface a stale
+ *  row. `null` when there is no open escalation. */
+export function latestOpenEscalationQuestion(rows: readonly PrEscalationRow[]): string | null {
+  let latest: PrEscalationRow | undefined;
+  for (const r of rows) {
+    if (r.status !== "open") continue;
+    if (!latest || r.id > latest.id) latest = r;
+  }
+  return latest?.question ?? null;
+}

package/db/migrations/034_user_tasks_inbox.sql

@@ -0,0 +1,51 @@
+-- Unified "Tasks" inbox read-model (issue #236) — surface EVERY open native user-task escalation
+-- awaiting a human decision in the nwf UI, so an operator can resolve one without leaving the app.
+--
+-- The four migrated escalations (ADR 0046) are native BPMN `userTask`s with linked `.form`s:
+-- `feature-escalation` (a stuck single-issue run), `feature-blocked` (a blocked run to acknowledge),
+-- `plan-review-decision` (a plan-review cap escalation), `trial-merge-decision` (a red trial merge),
+-- and the PR review-loop `wait-answer`. The completable user-task keys were only ever denormalised
+-- for the FEATURE kinds (migrations 031/032, onto `feature_runs`); the epic/PR kinds had NO app-side
+-- pointer at all, so the only surface that listed them was Urban's read-only `taskInbox` stub.
+--
+-- This is the schema-driven pages' single source for the Tasks page `dataGrid`s: `pollUserTasks`
+-- (app/service.ts) reconciles one row per currently-open escalation user task from the engine
+-- (`searchUserTasks`), denormalising the completable `user_task_key` plus display context (the
+-- escalation `question`, its `subject_*`, and `element_id`). A row exists iff the user task is open;
+-- the poller deletes a row once its task is gone (answered here, via the task inbox, or out-of-band),
+-- so `showCount` reflects live pending work. The completion affordances post the typed form variables
+-- to the canonical human completer (`completeEscalationAsHuman` / the existing feature answer/ack
+-- operations), the same resume path the task inbox uses — no parallel completion.
+--
+-- Forward-only, additive (expand): a brand-new table, no existing shape touched. Numbered after the
+-- current highest prefix (033); the runner wraps each file in its own transaction, so this file must
+-- NOT contain BEGIN/COMMIT.
+CREATE TABLE user_tasks (
+  -- The completable native user-task key (the engine's `userTaskKey`) — the PK, since a user task is
+  -- open at most once and every completion affordance posts to it.
+  user_task_key TEXT PRIMARY KEY,
+  -- The BPMN `elementId` of the parked user task (one of the migrated escalation elements). Drives
+  -- which typed decision form / completion operation the page routes the answer through.
+  element_id    TEXT NOT NULL,
+  -- Human-readable kind label for the grid (e.g. "Plan review", "Trial merge").
+  kind_label    TEXT NOT NULL,
+  -- The domain subject the escalation belongs to: `subject_type` is feature | plan | pr; `subject_key`
+  -- is its aggregate key (feature_key / plan_key / pr_key); `subject_url` is an optional external link
+  -- (the issue/PR URL) shown as a clickable column.
+  subject_type  TEXT NOT NULL,
+  subject_key   TEXT NOT NULL,
+  subject_url   TEXT,
+  -- The escalation question / findings the agent (or loop) raised, denormalised for display so the
+  -- operator can decide without opening the process. Best-effort; NULL when none was recorded.
+  question      TEXT,
+  -- The owning process instance key, for the process-explorer link. NULL when unknown.
+  process_key   TEXT,
+  created_at    TEXT NOT NULL,
+  updated_at    TEXT NOT NULL
+);
+
+-- The pages filter the grid by `element_id` (one grid per kind) and order by recency
+-- (`WHERE element_id IN (...) ORDER BY updated_at DESC`). A single composite index on
+-- `(element_id, updated_at)` serves both the equality filter and the ordered read in one structure —
+-- no extra sort/scan — so the read stays O(matching), not O(all open tasks), as the table grows.
+CREATE INDEX idx_user_tasks_element_updated ON user_tasks(element_id, updated_at);

package/docs/adr/0004-shared-contract-coordination.md

@@ -0,0 +1,108 @@
+# ADR 0004 — Coordinate shared contracts through a durable registry + a blackboard signal + a reconciliation pass
+
+Status: **Proposed.**
+Date: 2026-08-14.
+
+> **Scope note.** A **nano-workforce-local** ADR — it governs how *this app* coordinates cross-cutting
+> contracts across parallel/sliced agent work. Platform-wide ADRs live in
+> `Magikcraft/nano-bpm/docs/adr` (referenced by number + repo). Continues nano-workforce's series after
+> ADR 0001–0003.
+
+Relates to:
+issue **#227** (the framing + spec this ADR records the decision for),
+issue **#223** (the concrete `NANO_PR_*` env-key synonym cleanup — this ADR makes its cascade impossible
+to reintroduce),
+nano-ide **#234 / #236** (the relay producer/hub wire-shape drift — the same failure mode in a wire
+contract),
+issues **#214** (real-entrypoint integration test) and **#217** (retro verifies acceptance) — the
+after-the-fact verification this ADR complements with an authoring-time preventive,
+and in this repo: `app/contracts.ts` (the registry + typed env schema + declaration-conflict
+detection), `app/contractReconcile.ts` (the reconciliation pass), `app/blackboard.ts`
+(the `contract` kind + coordination brief), `operations/appendBlackboard.ts`,
+`scripts/check-contracts.ts` (the CI gate) and `scripts/reconcile-contracts.ts` (the advisory pass).
+
+## Context
+
+Parallel and sliced agent work keeps producing **two divergent representations of a single contract**,
+with no mechanism that binds them at authoring time. Two live examples of the *same* failure mode:
+
+1. **Config-key synonym** — `publicBaseUrl()` read `NANO_PR_PUBLIC_BASE_URL` and fell back to a phantom
+   `NANO_PR_BASE_URL` (introduced in the same commit, #53/2dcfb8a; nothing set it, the unit test even
+   exercised the wrong name). Two names for one value (#223). (`NANO_PR_PUBLIC_BASE_URL` was itself
+   later coalesced into the canonical `NANO_WORKFORCE_BASE_URL` in #226; both retired names are now
+   registered rejected synonyms.)
+2. **Wire-shape drift** — a relay *producer* kept emitting the legacy `{stream, offset, chunk}` frame
+   while the *hub* had adopted an op-tagged `{op:"produce", …}` sub-protocol; the hub rejected every
+   worker terminal chunk. Every isolated slice test was green because each side tested against its own
+   fake (nano-ide #234/#236).
+
+The through-line: **a contract (an env key, a wire shape, a shared type name, a capability-URL scheme) is
+authored independently by parallel workers, each against a mock or a local assumption, and the divergence
+is discovered only at runtime.** Existing issues are *after-the-fact verification* (#214, #217) or fix a
+*single symptom* (#223). None coordinate the shared contract surface **while** siblings are authoring it,
+nor reconcile the accumulated blackboard for duplicate/synonymous declarations.
+
+## Decision
+
+Coordinate shared contracts with **three complementary mechanisms**, at deliberately different lifetimes.
+
+### 1. A durable, executable contract registry (source of truth)
+
+`app/contracts.ts` is a committed, reviewed, first-class registry of cross-cutting contracts —
+env/config keys, wire-frame shapes, shared exported type/interface names, and capability-URL schemes —
+each with an **owner** + **semantics**. It is *executable where possible*:
+
+- **Env/config keys are parsed through ONE typed schema** (`ENV_CONTRACTS` + `readEnv`/`readEnvOr`).
+  `readEnv(key)` takes a compile-time-checked `EnvKey`, so a synonymous or misspelled key is a **type
+  error**, never a silent runtime fallback. Each entry may record `rejectedSynonyms` — names we
+  deliberately retired (e.g. `NANO_PR_BASE_URL`); their reappearance in code is a **CI failure**
+  (`scripts/check-contracts.ts`). The base-URL boundary is the migrated reference: `publicBaseUrl()` now
+  reads the schema and the phantom fallback is gone, so the #223 cascade **cannot be reintroduced**.
+- **Wire/type/capability-URL contracts** are declared alongside so ONE registry answers "does a contract
+  for X already exist?" for every category. The blackboard's `BlackboardEntry` snake_case shape and the
+  blackboard capability-URL scheme are the seed entries.
+
+### 2. A blackboard `contract` kind (the live, in-flight signal)
+
+`app/blackboard.ts` adds an app-recognised `contract` kind, **derived** from the shared store's kinds
+(`APP_BLACKBOARD_KINDS = [...BLACKBOARD_KINDS, "contract"]`) so the two never drift. An agent posts a
+`contract` entry ("I am introducing / consuming env key / wire op / type X") **as soon as it is true**,
+so siblings in a wave see a new contract *before* they independently invent a synonym. The coordination
+brief (`renderCoordinationBrief`) now requires: before introducing a new env key / wire field / shared
+type, **consult the registry and the blackboard `contract` entries**; if a semantically-equivalent one
+exists, **reuse it**; otherwise declare it in both. The registry is the durable truth; the blackboard is
+the live signal. **Neither alone suffices.**
+
+### 3. A de-duplication / reconciliation pass
+
+- **Write-time.** A `contract` POST runs near-duplicate *declaration* detection
+  (`detectDeclarationConflicts`, surfaced through `operations/appendBlackboard.ts` alongside the existing
+  `file-claim` conflict reporting): it flags a **synonym** (same semantics, different name), a
+  **contradiction** (same name, different meaning), or a **rejected synonym**, so the writer reconciles
+  at authoring time.
+- **Reconciliation pass** (`app/contractReconcile.ts`, a sibling to the L2 retro). It reads the *whole*
+  blackboard + the registry and flags synonyms, contradictions, and **mock-vs-real skew** (a contract
+  signalled in-flight that never landed in the durable registry). Advisory: it emits a report as an
+  escalation / merge candidate (`npm run reconcile:contracts`) rather than silently accumulating. The
+  mechanically-enforceable, registry-only half is the hard CI gate `npm run check:contracts`.
+
+## Consequences
+
+- The #223 failure mode is **categorically** closed for env keys: the synonym is a compile error and a
+  rejected synonym is a CI failure — not a runtime fallback.
+- A new cross-cutting contract has ONE place to be declared and ONE way to be read; the coordination brief
+  routes agents through it, and the reconciliation pass catches what slips through.
+- A CI gate (`check:contracts`) and an advisory pass (`reconcile:contracts`) make the coordination
+  observable rather than a hope.
+
+## Open questions / follow-ups
+
+- **Promote the `contract` kind into `@nanobpm/agentic/blackboard`.** The shared store's normaliser coerces
+  unknown kinds to `note`; the app persists `contract` by patching the row after the store's insert
+  (reusing the store's append so the idempotency logic is not duplicated). The durable home for this kind
+  is the shared package — a follow-up version bump removes the app-local patch.
+- **Migrate the remaining env call sites** (`app/service.ts`, `app/plan.ts`, `main.ts`, …) onto
+  `readEnv`/`readEnvOr`. The registry already declares every config key and the CI gate enforces
+  declaration; routing every read through the typed schema is a mechanical follow-up.
+- **Wire the reconciliation pass into the retro process** as an automatic cross-epic step, rather than an
+  operator-run script.

package/nano.app.json

@@ -66,7 +66,8 @@
       "statusField": "status",
       "activeStatuses": [
         "running",
-        "escalated"
+        "escalated",
+        "awaiting_operator"
       ],
       "onTerminated": {
         "set": {

package/openapi.yaml

@@ -864,6 +864,30 @@ components:
                 type: string
               created_at:
                 type: string
+        contractConflicts:
+          type: array
+          description: >-
+            Near-duplicate contract-DECLARATION conflicts on a `contract` POST (issue #227): a
+            synonym, contradiction, or rejected synonym vs. the durable contract registry. Advisory —
+            surfaced so the writer reconciles a divergent contract at authoring time; never a lock.
+          items:
+            type: object
+            additionalProperties: false
+            required:
+              - kind
+              - proposedName
+              - existingName
+              - detail
+            properties:
+              kind:
+                type: string
+                enum: [synonym, contradiction, rejected-synonym]
+              proposedName:
+                type: string
+              existingName:
+                type: string
+              detail:
+                type: string
     AbandonStatus:
       type: object
       required:
@@ -1244,6 +1268,59 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
+  /actions/complete-user-task:
+    post:
+      operationId: completeUserTask
+      summary: "Complete an open native user-task escalation from the nwf Tasks inbox (issue #236).
+        Submits the parked task's typed `.form` variables (e.g. a plan-review `{ directive, notes }`, a
+        trial-merge `{ action, notes }`, or a PR `{ answer }`) to the canonical human completer
+        (completeEscalationAsHuman → completeUserTaskAttributed) — the same resume path the task inbox
+        uses, recording who answered. The completer refuses any user task that is not one of the
+        migrated escalation elements. The feature-run kinds keep their own operations
+        (answer-escalation / acknowledge-blocked); this door is for the plan-review / trial-merge / PR
+        `wait-answer` kinds whose completion is a straight typed pass-through. On success the answered
+        task's read-model row is dropped so the Tasks grid stops offering a decision for it."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+                - userTaskKey
+                - variables
+              properties:
+                userTaskKey:
+                  type: string
+                  minLength: 1
+                  description: The parked escalation user-task key (user_tasks.user_task_key).
+                variables:
+                  type: object
+                  additionalProperties: true
+                  description: The typed form variables the parked task's `.form` expects (kind-specific).
+                operator:
+                  type: string
+                  description: Optional operator handle recorded in the attribution ledger; defaults to "operator".
+      responses:
+        "200":
+          description: The escalation user task was completed and the process resumed.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "400":
+          description: A required field was missing/invalid, or the target is not an escalation task.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No open escalation user task matches the userTaskKey.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
   /actions/acknowledge-blocked:
     post:
       operationId: acknowledgeBlocked

package/operations/appendBlackboard.ts

@@ -7,11 +7,15 @@
 //   POST → append one entry: { author_task?, kind?, files?, body, wave?, dedupe_key? }. Idempotent
 //          on (plan, dedupe_key). Returns { id, inserted, conflicts } — `conflicts` lists prior
 //          sibling `file-claim`s on the same file(s) (advisory first-writer-wins; never a lock).
+//          A `contract` POST additionally returns `contractConflicts` (near-duplicate declaration
+//          conflicts vs. the durable registry, #227); the field is absent for other kinds, per the
+//          OpenAPI schema's optional property.
 
 import {
   appendEntry,
+  detectContractDeclarationConflicts,
   detectFileClaimConflicts,
-  normalizeKind,
+  normalizeAppKind,
   planKeyForToken,
 } from "../app/blackboard.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
@@ -28,40 +32,56 @@ export default defineOperation("appendBlackboard", async ({ req, body }, app) =>
   const b = body ?? {};
   const text = typeof b.body === "string" ? b.body.trim() : "";
   if (!text) return { status: 400, body: { error: "'body' (the note text) is required" } };
-  const kind = normalizeKind(b.kind);
+  const kind = normalizeAppKind(b.kind);
   const files = Array.isArray(b.files) ? b.files.map(String) : [];
   // Normalize once (trim + default to "system") so the value we send to appendEntry matches the
   // value we send to detectFileClaimConflicts. Otherwise an omitted/blank author_task is stored as
   // "system" but conflict detection sees "", and the caller's own prior "system" claims are wrongly
   // reported as sibling conflicts.
   const author_task = (typeof b.author_task === "string" ? b.author_task.trim() : "") || "system";
+  // Trim before it becomes the idempotency key: `dedupe_key` backs a unique index (and is now also
+  // parsed for the `<category>:<name>` contract ref), so accidental leading/trailing whitespace would
+  // otherwise slip past dedupe and create near-identical entries. A blank-after-trim key is no key.
+  const dedupe_key = typeof b.dedupe_key === "string" ? b.dedupe_key.trim() || undefined : undefined;
   const res = await appendEntry(app.data, planKey, {
     author_task,
     kind,
     files,
     body: text,
     wave: typeof b.wave === "number" ? b.wave : null,
-    dedupe_key: typeof b.dedupe_key === "string" ? b.dedupe_key : undefined,
+    dedupe_key,
   });
-  // Advisory conflict-of-intent: surface prior sibling claims on the same file(s). Computed AFTER
-  // the append and filtered to claims strictly before ours (id < res.id), so first-writer-wins is
-  // decided by insertion order — a sibling that raced a claim in between is still caught, and our
-  // own just-written row is never reported. Never blocks the append — the agent decides how to react.
+  // Advisory conflict-of-intent. For a `file-claim`, surface prior sibling claims on the same
+  // file(s) — computed AFTER the append and filtered to claims strictly before ours (id < res.id),
+  // so first-writer-wins is decided by insertion order (a sibling that raced a claim in between is
+  // still caught, and our own just-written row is never reported). Never blocks the append.
   const conflicts = kind === "file-claim"
     ? await detectFileClaimConflicts(app.data, planKey, {
       author_task,
       files,
-      beforeId: Number(res.id),
+      beforeId: res.id,
     })
     : [];
+  // For a `contract`, surface near-duplicate DECLARATION conflicts (a synonym/contradiction/rejected
+  // synonym vs. the durable registry) so a writer reconciles a divergent contract at authoring time
+  // (#227). Advisory — the agent decides how to react.
+  const contractConflicts = kind === "contract"
+    ? detectContractDeclarationConflicts({ dedupe_key, body: text })
+    : [];
   app.log.info("blackboard entry appended", {
     planKey,
     kind,
     inserted: res.inserted,
     conflicts: conflicts.length,
+    contractConflicts: contractConflicts.length,
   });
   return {
     status: res.inserted ? 201 : 200,
-    body: { id: Number(res.id), inserted: res.inserted, conflicts },
+    // `contractConflicts` is only meaningful on a `contract` POST and is optional in the schema, so
+    // omit it entirely for other kinds rather than emitting an always-empty array (keeps the response
+    // shape aligned with the OpenAPI contract, which does not require the field).
+    body: kind === "contract"
+      ? { id: res.id, inserted: res.inserted, conflicts, contractConflicts }
+      : { id: res.id, inserted: res.inserted, conflicts },
   };
 });

package/operations/blackboard.test.ts

@@ -100,6 +100,18 @@ test("POST is idempotent on dedupe_key (retry → 200, not a duplicate)", async
   assertEquals(n, 1);
 });
 
+test("POST dedupe_key is trimmed → a whitespace-padded retry still dedupes to one row (#227)", async () => {
+  const { app, db } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  assertEquals((await call(app, "POST", { token: "tok" }, { author_task: "t", body: "claim", dedupe_key: "t:claim:1" })).status, 201);
+  // A retry whose key only differs by leading/trailing whitespace must NOT slip past dedupe.
+  const padded = await call(app, "POST", { token: "tok" }, { author_task: "t", body: "claim", dedupe_key: "  t:claim:1  " });
+  assertEquals(padded.status, 200);
+  assertEquals(padded.body.inserted, false);
+  const [{ n }] = db.all<{ n: number }>("SELECT COUNT(*) AS n FROM agentic_blackboard WHERE scope = ?", ["o/r#1"]);
+  assertEquals(n, 1);
+});
+
 test("GET ?since returns only newer entries", async () => {
   const { app } = memApp();
   await seedPlan(app, "o/r#1", "tok");
@@ -175,4 +187,41 @@ test("POST a non-file-claim carries no conflicts", async () => {
   await seedPlan(app, "o/r#1", "tok");
   const res = await call(app, "POST", { token: "tok" }, { author_task: "t", kind: "note", body: "fyi" });
   assertEquals(res.body.conflicts, []);
+  // `contractConflicts` is optional in the schema and only meaningful on a `contract` POST — a
+  // non-`contract` response omits it entirely rather than emitting an always-empty array (#229).
+  assertEquals("contractConflicts" in res.body, false);
+});
+
+test("POST kind='contract' persists the contract kind and round-trips through GET (#227)", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  const post = await call(app, "POST", { token: "tok" }, {
+    author_task: "task-a",
+    kind: "contract",
+    dedupe_key: "env:NANO_WIDGET_TIMEOUT",
+    body: "introducing env key NANO_WIDGET_TIMEOUT — app/widget.ts — widget request timeout in ms",
+  });
+  assertEquals(post.status, 201);
+  // No existing contract matches, so no declaration conflicts.
+  assertEquals(post.body.contractConflicts, []);
+
+  const get = await call(app, "GET", { token: "tok" });
+  assertEquals(get.body.entries.length, 1);
+  // The store's normaliser would coerce an unknown kind to 'note'; the adapter restores 'contract'.
+  assertEquals(get.body.entries[0].kind, "contract");
+});
+
+test("POST kind='contract' reintroducing a rejected synonym surfaces a declaration conflict (#223/#227)", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  const post = await call(app, "POST", { token: "tok" }, {
+    author_task: "task-b",
+    kind: "contract",
+    dedupe_key: "env:NANO_PR_BASE_URL",
+    body: "base url for the app",
+  });
+  assertEquals(post.status, 201);
+  assertEquals(post.body.contractConflicts.length >= 1, true);
+  assertEquals(post.body.contractConflicts[0].kind, "rejected-synonym");
+  assertEquals(post.body.contractConflicts[0].existingName, "NANO_WORKFORCE_BASE_URL");
 });