​

spec_id: SPEC-029 version: “0.2” title: Agent nudges — persistent cross-session reminders for implicit obligations status: draft supersedes: (SPEC-029 v0.1 conversational draft, never filed)

​

SPEC-029 v0.2 — Agent nudges

​

1. Summary

​

2. Origin

1. SPEC-023 already rejected auto-wrap on start — “produces artifact that looks like wrap but isn’t.” v0.1’s delta_kind='auto_wrap' enum extension was a workaround, not a fix.
2. Concurrent sessions (Lola on Claude Desktop + Donna on Claude Code) — a time-threshold-based auto-wrap would silently close a live-but-quiet session. No liveness signal exists in the current model.

​

3. Problem

1. Abandoned sessions stay invisible. SPEC-023 §5.4 detects unwrapped prior sessions by delta-sequence heuristic. The signal is lossy — it rebuilds state from delta history every call, with no persistent marker of “this session owes a wrap.”
2. Draft-arc abandonment. A SPEC filed as status=draft or an ADR as status=proposed has no future-surface reminder. It lives in prism_*(action=list) output, which agents rarely scan proactively.
3. Cross-session obligations have no primitive. WIP states, open invites, outstanding handoffs — each is tracked in its own table with its own surfacing convention (if any). No uniform “open things that need attention” query exists.

​

4. Schema

• (tenant_id, project_id, resolved_at) partial WHERE resolved_at IS NULL — fast open-nudge listing
• (kind, source_type, source_id) — fast auto-resolution lookup
• (snooze_until) partial WHERE resolution='snoozed' — reopener sweep

​

4.1 Nudge kinds (v1)

​

5. Write semantics

1. Use the kind’s canonical source_type + source_id per §4.1.
2. Idempotence: if an open nudge already exists with the same (kind, source_type, source_id), do not write a duplicate. The write path is an UPSERT on resolved_at IS NULL — existing open row wins, new write is a no-op. Audit counter in metadata optional.
3. Failure-soft: nudge write errors must NEVER fail the parent verb. Log-and-proceed. (Matches prism_wrap patch_project pattern, mcp/server.py:1618–1634.)

• Write a nudge with a kind not in §4.1.
• Write a nudge whose source_id refers to an entity that doesn’t exist.
• Write a nudge with severity=blocking (reserved for future spec; v1 enum is info | nudge only).

​

6. Resolution semantics

​

6.1 Auto-resolution on state change (preferred)

UPDATE nudges
   SET resolved_at = now(),
       resolved_by_verb = '<verb>',
       resolution = 'auto_cleared'
 WHERE kind = '<kind>'
   AND source_type = '<source_type>'
   AND source_id = '<source_id>'
   AND resolved_at IS NULL;

​

6.2 Manual resolution (user-initiated)

prism_nudge(pid, action, nudge_id?, resolution?, resolution_note?, snooze_hours?)

• list — returns open nudges for the project (optional filter by kind).
• resolve — sets resolved_at, resolution=ignored|completed|snoozed, resolved_by_verb='prism_nudge.resolve', plus optional note.
• snooze — shortcut for resolve with resolution='snoozed' plus snooze_until = now() + snooze_hours.

​

6.3 Scheduled re-opening (snooze sweep)

​

7. Surfacing contract

"pending_nudges": [
  {
    "id": "...",
    "kind": "wrap_session",
    "source_id": "<prior session_id>",
    "message": "Prior session has 3 unwrapped deltas, last activity 2026-04-22T11:41Z",
    "actions": ["wrap", "continue", "ignore", "snooze"],
    "metadata": { "persona": "Lola", "delta_count": 3,
                  "orphan_summaries": ["docs-hero-diagram-rewrite ...",
                                        "docs-overview-rewrite-and-vision-plp ...",
                                        "docs-history-shipped ..."] }
  }
]

If pending_nudges is non-empty in the prism_start return, the agent MUST present the open nudges at the top of the first substantive response, with their available actions clearly offered to the user. The agent proceeds with the user’s current request only after either (a) the user has chosen an action for each nudge, or (b) the user has explicitly said to defer (“later”, “ignore for now”), in which case the agent writes a snooze with a sensible default (1 hour) and proceeds.

"rules_reminders": [ /* computed, ephemeral */ ],
"pending_nudges": [ /* persistent, actionable */ ]

​

8. Agent contract: when to write a nudge

1. Does the action create an implicit obligation a future surface should check on? If no → no nudge.
2. Is the obligation cheaply recomputable at read time? If yes → keep in rules_reminders (ephemeral, no storage).
3. Is the obligation an explicit user work item? If yes → use prism_todo, not a nudge.
4. Is the obligation scoped to a specific entity’s lifecycle that already has a resolution verb? If yes → nudge with the matching kind per §4.1.

​

9. Rejected alternatives

• SPEC-029 v0.1 silent auto-wrap — superseded by this spec. Objection: SPEC-023’s “artifact that looks like wrap but isn’t”; concurrency race with live-but-quiet sessions.
• Staleness threshold on the writer side — pushes “is this abandoned?” judgment to wall-clock math. Unreliable for live-but-idle sessions. Nudges defer that judgment to the user at read time instead.
• Reuse session_deltas as nudge storage — would overload delta_kind and mix ephemeral nudges with append-only history. Separate table keeps semantics clean.
• Blocking on start (hard-gate until user resolves) — violates SPEC-021’s soft-gate ethos; breaks scripted use. Kept as soft surfacing contract only.
• Scope-small v1 (wrap nudge only, defer others) — Frank: “I don’t want to create something else I need to come back later to complete. Only defer when I have to.” The five other kinds are trivial write hooks once the table exists; no reason to defer.

​

10. Implementation

​

10.1 Sequencing — single PR (est. 1 day)

​

10.2 Historical backfill (one-shot, same migration)

• At least one non-wrap delta exists
• No wrap delta exists for that session_id

​

10.3 Observability

• Counter: nudges_opened_total{kind} (30d rolling)
• Counter: nudges_resolved_total{kind, resolution} (30d rolling)
• Gauge: nudges_open{kind} (current open count per kind)
• Derived: per-kind median age, resolution rate, snooze rate.

​

10.4 Install / deploy impact

​

11. Relationships

• Extends SPEC-023 — replaces its §5.4 detection heuristic with persistent nudge rows. SPEC-023’s delta_kind column, session_id minting, and wrap_rate observability all stand.
• Uses SPEC-022’s last_wrapped_* columns unchanged. Auto-resolution of wrap_session on prism_wrap still patches those columns per SPEC-022 before resolving the nudge.
• Supersedes SPEC-029 v0.1 (conversational draft; never filed; preserved in session deltas).
• Related SPEC-021 Ring 0 — nudge surfacing uses the status-card / bootstrap contract as its delivery channel but does not add new gates.
• Informs future spec on org-level nudges (project_id=null) — deliberately scoped out of v1.

​

12. Open questions

• Q1: Default snooze duration — 1h in the agent contract (§7). Tune with usage; revisit after 30d of data.
• Q2: Should handoff_pending auto-resolve on the next persona’s prism_start (as an implicit ack)? Lean no: handoff acknowledgment should be explicit. Defer to follow-up spec.
• Q3: Should spec_draft and adr_proposed nudges self-snooze if the draft is being actively edited (delta activity in the last hour referencing the spec_id)? Lean no in v1; nudges are about cross-session memory, not intra-session noise. Revisit if users complain.
• Q4: Do we need an org_nudges table or can org-scoped nudges reuse this table with project_id=null? Lean reuse with null. Defer until first org-level use case.
• Q5: Per-project agent-contract overrides (e.g. “this project: block on wrap_session, don’t for other kinds”) — deferred to follow-up SPEC. v1 is uniform across projects.

​

13. Acceptance criteria

1. ✅ nudges table exists with all columns + indexes per §4.
2. ✅ prism_start returns pending_nudges array; empty when no open nudges exist.
3. ✅ prism_wrap on session_id X auto-resolves any open wrap_session nudges with source_id=X and does not resolve nudges with different source_ids (concurrency test).
4. ✅ Writing two wrap_session nudges for the same session_id in a row results in exactly one open row (idempotence).
5. ✅ All six kinds in §4.1 have integration tests: write, auto-resolve on matching verb, manual resolve via prism_nudge.
6. ✅ Historical backfill (§10.2) populates expected wrap_session rows for known unwrapped session_ids on the Prism project.
7. ✅ Smoke test mcp/smoke_spec029.py passes locally + against server1.
8. ✅ BIOS templates updated with agent contract; propagated via prism_sync_bios.
9. ✅ rules_reminders no longer emits unwrapped_session entries; those are replaced by pending_nudges entries of kind=wrap_session.
10. ✅ Wrap-rate metric (SPEC-023 §7) unchanged behaviorally.