goal-manual v0.2.2A

Immutable. This exact content is served forever at /api/v1/blob/87736031d9e4ad7e.

---
name: goal-manual
description: >
  Goal notification manual: `.notification/goal.json` source-of-truth, fields,
  instructions, idle reminders, protected dismiss behavior, and cancellation or
  completion semantics.
version: 0.2.2
tags: [lingtai, goal, notifications, reminders]
last_changed_at: 2026-07-27T00:00:00Z
related_files:
- src/lingtai/intrinsic_skills/system-manual/SKILL.md
- src/lingtai/kernel/nudge/goal.py
maintenance: |
  Tracks the goal-notification topic it documents; update when that integration changes.
---

# Goal Manual

A goal is represented by `.notification/goal.json`. This file is the protected
source of truth for the agent's current active goal. The short reminder event only
points the agent back to this file; it does not contain the goal details.


## Guided setup via `/goal`

`/goal` is the TUI entry point for human-guided goal creation. It does **not**
write `.notification/goal.json` directly. Instead, the TUI appends a system event
to `.notification/system.json` so the running agent can guide the human before
creating or changing the goal file:

```json
{
  "source": "goal.request",
  "ref_id": "goal.request:<timestamp>",
  "body": "Human wants to set or revise an active goal..."
}
```

When you receive a `source="goal.request"` event:

1. **Read this manual first.** The event is a request to guide goal creation, not
   permission to invent goal details.
2. **Explain the mechanism briefly to the human.** Tell them that an active goal
   lives in `.notification/goal.json`, idle reminders are short
   `goal.reminder` system events, and dismissing a reminder only hides the
   reminder.
3. **Ask for the missing goal fields.** At minimum, clarify:
   - objective: what should be accomplished;
   - criteria: how the human and agent will know it is done;
   - status/id: a stable `data.id` and active status if the goal should start
     now;
   - reminder cadence: optional `data.reminder_delay_seconds`;
   - constraints: deadlines, channels to report on, what not to do, or approval
     gates.
4. **Explain cancellation and completion before writing** — see "Protected
   dismiss behavior" below for the exact semantics.
5. **Write `.notification/goal.json` only after confirmation.** If the human gave
   a complete inline draft with `/goal <text>`, restate the structured goal and
   ask for confirmation unless the instruction explicitly and unambiguously says
   to create it now.
6. **Dismiss the request after handling it.** Use the event `ref_id` so other
   system events survive:

```text
notification(action="dismiss_ref",
             input={"ref_id": "goal.request:<timestamp>", "channel": null,
                    "force": null, "reason": null},
             reasoning="the goal request is handled")
```

If the human changes their mind during setup, dismiss the `goal.request` event
without creating `goal.json`. If a previous active goal exists, do not overwrite
it silently; explain the existing goal and ask whether to complete, cancel, or
replace it.

## Minimal goal file

```json
{
  "header": "Active goal: finish notification PR",
  "icon": "🎯",
  "priority": "high",
  "published_at": "2026-06-10T00:00:00Z",
  "instructions": "Current active goal. Read data.objective and data.criteria. This channel is protected: do not dismiss it. To cancel the goal, delete .notification/goal.json. See the goal manual under system-manual.",
  "data": {
    "id": "notification-pr",
    "status": "active",
    "objective": "Implement notification whitelist, atomic system-event dismiss, and goal reminders.",
    "criteria": ["tests pass", "manuals updated", "PR opened"],
    "reminder_delay_seconds": 120
  }
}
```

Recommended fields live under `data`:

- `id`: stable identifier used by reminders as `ref_id="goal:<id>"`.
- `status`: omit or use `active` for active work. `done`, `complete`,
  `completed`, `superseded`, `cancelled`, `canceled`, or `inactive` suppress
  reminders.
- `objective`: what to accomplish.
- `criteria`: what done means.
- `reminder_delay_seconds`: optional idle delay before a reminder. If absent, the
  runtime reuses the agent's soul delay; invalid values fall back safely.

The top-level `instructions` field should explicitly say to read the goal data,
that the `goal` channel is protected, and that this manual has the mechanism
details.

## Protected dismiss behavior

`goal` is not an ordinary dismissible notification mirror. Generic dismiss refuses:

```text
notification(action="dismiss_channel",
             input={"channel": "goal", "force": null, "reason": null},
             reasoning="...")  # refused
```

To cancel the goal, delete `.notification/goal.json` or mark `data.status`
`inactive`/`cancelled`/`canceled`. To complete or supersede it, mark
`data.status` `done`/`complete`/`completed`/`superseded`, or delete/replace the
file. Dismissing a `goal.reminder` does **not** cancel the goal. Agents are
trusted to decide when the source-of-truth file should change; the protection only
prevents misleading API semantics where dismissing a notification looks like
canceling a goal.

## Idle reminder behavior

The reminder trigger requires the source-of-truth file itself: if
`.notification/goal.json` is absent, no goal reminder is generated.

When `.notification/goal.json` exists, is active, and the agent remains IDLE for
the configured delay, the kernel publishes one short event into
`.notification/system.json`:

```json
{
  "source": "goal.reminder",
  "ref_id": "goal:<id>",
  "body": "Goal reminder: read .notification/goal.json and follow its instructions; see the goal manual under system-manual."
}
```

The reminder is intentionally brief. The actual goal and instructions stay in
`goal.json`. Dismissing the reminder clears only the system event:

```text
notification(action="dismiss_ref",
             input={"ref_id": "goal:<id>", "channel": null,
                    "force": null, "reason": null},
             reasoning="the goal reminder is handled")
```

Dismissing the reminder does not cancel the goal. If the goal remains active, a
fresh idle interval can generate another reminder. If `goal.json` is deleted or
marked inactive/done while a reminder is already present, the next IDLE goal
check clears that stale `goal.reminder` system event.

## Cross-reference

For notification channels, envelopes, allowlist behavior, and atomic system-event
dismiss, read the first-level `notification-manual` skill.