overlord-cli 0.2610241050.0 → 0.2610242007.0

package/dist/connectors/core/overlord-mission/SKILL.md

@@ -32,14 +32,18 @@ when none apply. Human actions are concrete work a user must perform outside com
 never include Git operations or routine review/testing. Every human action needs `action`, `reason`,
 and `category`; add `command`, `verify`, and `link` whenever they exist so the operator can act
 without re-reading the delivery (see **Delivery Evidence** below). Tradeoffs record the
-implementation decision, alternatives considered, and rationale. Each `deferredWork` item
-must be a recommended new objective that is not part of this mission (for example a bug
-discovered here that belongs outside it). Name the component or file involved and say why
-the work was left. Never list work already covered by this mission's future objectives,
-leftover slices of the current objective (add an objective to this mission instead), or
-human implementation follow-up such as deploy, secrets, or migrations (those belong in
-`humanActions`). Use an empty array when nothing qualifies. These fields improve
-review visibility but never block delivery.
+implementation decision, alternatives considered, and rationale.
+Each `deferredWork` item is one recommended objective outside this mission. Be very
+concise. `title` names the work in an imperative phrase. `change` states only the specific
+change that is needed. `location` says where to find it in the code: the file, function,
+component, or command. `doneWhen` states the observable result in one sentence. Do not add
+instructions on how to do the work, background, or rationale. The operator turns the item
+into an objective or a mission as written, so it must read as a task, not as a note.
+Never list work already covered by this mission's future objectives, leftover slices of
+the current objective (add an objective to this mission instead), or human implementation
+follow-up such as deploy, secrets, or migrations (those belong in `humanActions`). Use an
+empty array when nothing qualifies. These fields improve review visibility but never block
+delivery.
 
 For full command syntax, flags, phase values, and event types see **CLI Command Reference** below.
 
@@ -95,7 +99,7 @@ Use this mode when the conversation starts normally and the user asks the agent
 5. If the user wants to establish a persistent session with a mission by ID, run `ovld protocol attach --mission-id <mission_id>`.
 6. If the user wants to find a mission but does not know the ID, run `ovld protocol search-missions --query "..." --status execute,review` and ask the user to confirm.
 7. If you need to understand project routing before prompting, use `ovld protocol discover-project`.
-8. If the user wants to **record work that is already finished** in this chat (for example, something you just built in a chat app) as a completed mission, run `ovld protocol record-work --project-id <project-id>` (or the hosted `overlord_record_work` MCP tool). This creates a mission with one completed objective, records explicitly supplied changed files and optional rationales, lands it in the review column, and runs the standard Gemini delivery summary — all in one call, with no `attach`/`deliver`. Do **not** use it for in-progress work. The exact submission format is in [reference/record-work.md](reference/record-work.md).
+8. If the user wants to **record work that is already finished** in this chat (for example, something you just built in a chat app) as a completed mission, run `ovld protocol record-work --project-id <project-id>` (or the hosted `overlord_record_work` MCP tool). This creates a mission with one completed objective, records any paths you declare as Declared evidence, lands it in the review column, and runs the standard Gemini delivery summary — all in one call, with no `attach`/`deliver`. Do **not** use it for in-progress work. The exact submission format is in [reference/record-work.md](reference/record-work.md).
 9. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
 10. Once you attach to a mission, switch back to Mode 1 and follow the full mission lifecycle.
 
@@ -172,15 +176,18 @@ ovld protocol deliver --session-key <sessionKey> \
 ```
 
 This is the normal delivery shape: a summary is sufficient. The CLI syncs objective-ledger
-evidence independently before the lifecycle transition.
-
-After running a generator, migration, or script that writes files, you may add its known outputs
-to this existing call with `--paths path/one.ts,path/two.ts`. This is optional, paths-only
-metadata for outputs the native hook cannot name; never use it to enumerate every changed or
-opened file, and never make a separate call just to declare paths.
-
-Artifacts, optional change rationales, and a delivery report remain current annotations when
-they add review value. Use `--payload-json` when the full delivery object fits comfortably inline
+evidence independently before the lifecycle transition, and tracking gaps or sync failures never
+block delivery. See **Delivery And Change Evidence** below for how to prepare the summary.
+
+When you know you changed files that native capture could not name (shell or heredoc writes,
+script or generator outputs, deletes, and both endpoints of a rename), add exactly those to the
+same `update` or `deliver` call with `--paths path/one.ts,path/two.ts`, or `--paths-file <path|->`
+with a JSON string array when a path contains a comma or the list is long. They are recorded as
+Declared, never as native capture. Never use it to enumerate every changed or opened file, and
+never make a separate call just to declare paths.
+
+Artifacts and a delivery report remain optional annotations when they add review value. There
+is no per-file explanation input. Use `--payload-json` when the full delivery object fits comfortably inline
 (roughly under 8 KB). Larger inline `--*-json` values are rejected; stream them through the
 corresponding `--*-file -` flag. A real scratch path belongs under `$OVERLORD_TMPDIR` (this launch's private
 `.overlord/tmp/sessions/<id>/` directory); `deliver` removes that directory for you, and nothing
@@ -212,13 +219,31 @@ Only list a human action when a person must perform a concrete non-Git step outs
 agent's completed work (for example, add a secret, run a production migration, deploy, or
 configure an external integration). Never list committing, pushing, opening a pull request,
 reviewing code, or ordinary tests. A tradeoff must state the decision, alternatives considered,
-and rationale. Each `deferredWork` item must be a recommended new objective that is not
-part of this mission (for example a bug discovered here that belongs outside it). Name
-the component or file involved and say why the work was left. Never list work already
-covered by this mission's future objectives, leftover slices of the current objective
-(add an objective to this mission instead), or human implementation follow-up such as
-deploy, secrets, or migrations (those belong in `humanActions`). Use an empty array when
-nothing qualifies. Omit the report when none of these facts apply.
+and rationale.
+Each `deferredWork` item is one recommended objective outside this mission. Be very
+concise. `title` names the work in an imperative phrase. `change` states only the specific
+change that is needed. `location` says where to find it in the code: the file, function,
+component, or command. `doneWhen` states the observable result in one sentence. Do not add
+instructions on how to do the work, background, or rationale. The operator turns the item
+into an objective or a mission as written, so it must read as a task, not as a note.
+Never list work already covered by this mission's future objectives,
+leftover slices of the current objective (add an objective to this mission instead), or
+human implementation follow-up such as deploy, secrets, or migrations (those belong in
+`humanActions`). Use an empty array when nothing qualifies. Omit the report when none of these facts apply.
+
+#### Writing a deferred-work item
+
+| Field      | Limit     | What to write                                                       |
+| ---------- | --------- | ------------------------------------------------------------------- |
+| `title`    | 80 chars  | The work, as an imperative phrase. Shown as the row title.          |
+| `change`   | 400 chars | The specific change that is needed, in one or two sentences.        |
+| `location` | 200 chars | Where to find it: the file, function, component, or command.        |
+| `doneWhen` | 200 chars | The observable result, in one sentence.                             |
+
+All four fields are required. A plain string item is rejected with `invalid_input`.
+
+> Vague: `{ "title": "Fix flaky test", "change": "The sync worker has a flaky test.", "location": "backend", "doneWhen": "It passes." }`
+> Good: `{ "title": "Advance the fake clock before the second retry", "change": "The test asserts the retry fired but never advances the fake clock between attempts, so it passes or fails on real time.", "location": "backend/sync-worker.test.ts › retries after a 503", "doneWhen": "The test passes 20 consecutive runs with the fake clock driving both attempts." }`
 
 #### Writing a human action the operator can complete
 
@@ -260,21 +285,42 @@ migrations, `.env.example` changes, dependency manifests, CI workflow files) and
 them, so leaving one out never hides it; reporting it yourself with a real `command` and
 `verify` replaces the generic wording with something the operator can follow.
 
-### Change ledger health (diagnostic)
+### Reading captured file evidence
 
-Use this only to inspect or troubleshoot objective-ledger synchronization and hook health:
+Read the objective's captured paths once before you write the delivery summary:
 
 ```bash
-ovld protocol changes --mission-id $MISSION_ID
+ovld protocol changes --objective-id $OBJECTIVE_ID
 ```
 
-It may flush pending metadata-only ledger entries for the attached objective, then reports the
-binding, synchronization result, evidence source/quality, and bounded hook health. It does not
-read or diff the worktree, classify files by agent ownership, draft rationales, or gate delivery.
-Native paths normalized by the connector-owned codec as `file.edited` are valid, non-exclusive
-`declared_edit`/`direct` evidence. Codec-normalized read, search, and fetch callbacks are silent
-no-ops. Mutation-capable callbacks without a normalized edit path, plus shell, generic, unknown,
-and unmapped callbacks, report unavailable evidence health.
+This is a local read of this checkout's sessions for the objective. It syncs pending ledger
+entries first (sync failure is advisory), then returns synced and pending paths deduplicated by
+path, capped at 200 rows with a pre-cap `total` and `truncated`, plus capture and sync warnings.
+`coverage: "unavailable"` means no local session matched, not "no files changed". It is not
+complete cross-device history: `ovld protocol objective-changes --objective-id $OBJECTIVE_ID`
+(hosted MCP `overlord_changes`) reads the objective's synchronized evidence across sessions,
+resources, and devices, but cannot see unsynchronized local rows. Neither read diffs the
+worktree, classifies ownership, or gates delivery.
+
+Each row is cumulative objective evidence, including edits later reverted, with a source:
+
+- `declared_edit` (shown as Native): at least one successful native edit callback named the path.
+- `agent_declared` (shown as Declared): you or a record-work call declared the path.
+- `null` (shown as Unknown): historical evidence whose provenance could not be established.
+
+Native capture appends a path only for a codec-normalized edit whose outcome is successful.
+Reads, searches, and fetches are silent. Warnings tell you where capture may be incomplete:
+
+- `shell_activity_unverified`: a shell command ran; it may or may not have written files.
+- `outcome_partial` / `outcome_unavailable`: an edit failed partway or its result was unknown,
+  so no path was recorded.
+- `direct_path_unavailable`: a tool ran that capture cannot map to paths.
+- Binding warnings: tracking was not active for the session (unbound), is configured but no
+  callback has been observed, or its availability is unknown (hosted).
+- Sync warnings: some captured paths have not synchronized yet.
+
+A warning is not proof that a file changed. Declare only files you know you changed and capture
+missed; when unsure, say in the summary that coverage may be incomplete instead of guessing.
 
 ### Shared worktree safety (critical)
 
@@ -291,42 +337,33 @@ uses the same summary-only delivery as every other objective.
 
 Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
 
-### Optional Change Rationales
-
-Rationales are optional annotations. Overlord records which files an objective changed on its
-own, so a delivery never needs them and can never fail for lacking them. Supply one only when
-the reason for a change is not obvious from the diff.
+### Declaring paths native capture missed
 
-Attach them to `update` while working, or to `deliver` at the end. Inline
-`--change-rationales-json` is fine for a few entries; larger arrays are **rejected** — use
-`--change-rationales-file -` and stream JSON on stdin. The same ~8 KB inline limit applies to
-`--payload-json` and other `--*-json` flags.
+Per-file explanations no longer exist: `--change-rationales-*`, `--changed-files-*`, and the
+`changeRationales` / `changedFiles` payload fields are rejected. Explain changes in the summary.
 
-**Fields per entry:** `filePath`, `label`, `summary`, `why`, `impact` (all strings).
-Use the canonical `filePath` spelling. Do not wrap the entry under a `rationale` key.
-
-**Never revert, restore, or delete file changes from other agents or missions.** Leave
-unrelated dirty files intact.
+Declare known misses on the call you are already making. A rename declares both endpoints, and
+a deleted or renamed-away path is valid even though it no longer exists:
 
 ```bash
-ovld protocol update --session-key <sessionKey> --mission-id $MISSION_ID \
-  --summary "Added retry logic." --phase execute \
-  --change-rationales-json '[{"label":"Add backoff","filePath":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x.","hunks":[{"header":"@@ -22,4 +22,18 @@"}]}]'
+ovld protocol deliver --session-key <sessionKey> --objective-id $OBJECTIVE_ID \
+  --summary "Narrative: what you did and next steps." \
+  --paths src/generated/schema.ts,docs/old-name.md,docs/new-name.md
 ```
 
-For many entries (roughly 5+), stream them through `--change-rationales-file -` to avoid shell quoting failures:
+For a long list, or a path containing a comma, stream a JSON string array:
 
 ```bash
-ovld protocol deliver --session-key <sessionKey> --mission-id $MISSION_ID \
+ovld protocol deliver --session-key <sessionKey> --objective-id $OBJECTIVE_ID \
   --summary "Narrative: what you did and next steps." \
-  --change-rationales-file - <<'EOF'
-[
-  {"label":"Add backoff","filePath":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x."},
-  {"label":"Update config","filePath":"lib/config.ts","summary":"Added timeout.","why":"Match new defaults.","impact":"Requests time out after 30s."}
-]
+  --paths-file - <<'EOF'
+["src/generated/schema.ts", "fixtures/a,b.json"]
 EOF
 ```
 
+Paths are normalized against the checkout. Traversal, symlinks that leave the checkout, ignored
+paths, and Overlord-managed paths are rejected with a reason on stderr and never fail the call.
+
 ### Project Discovery And Mission Creation
 
 When creating missions from within a repository:
@@ -427,19 +464,25 @@ A checkout may be linked to more than one project. Default mission association t
 
 ## Delivery And Change Evidence
 
-Normal delivery contains the narrative summary only. The CLI synchronizes objective-ledger
-evidence independently; neither the agent nor a shared working tree supplies an ownership list.
-
-- Add a change rationale only when a non-obvious implementation reason materially helps review.
-- Do not send `file_changes` as an artifact or reconstruct paths from `git status`.
-- `ovld protocol changes` is a ledger-sync and hook-health diagnostic. It does not classify
-  ownership or draft annotations.
-- Do not include unrelated worktree changes in delivery annotations or artifacts.
+The reviewer sees your summary and, separately, a cumulative **Files changed during this
+objective** list grouped by resource. Prepare delivery cheaply:
+
+1. Read the captured paths once (`ovld protocol changes --objective-id <id>`, or
+   `overlord_changes` over MCP). See **Reading captured file evidence** above.
+2. If capture warns about shell, partial, or unsupported activity and you know of files you
+   changed that it missed, declare exactly those with `--paths` / `--paths-file` on `deliver`.
+3. Write the summary by behavior or component: the outcome, why it matters, how you verified it,
+   and material limitations, including any capture gap you could not reconcile. A handful of
+   representative paths is enough; never enumerate every file or explain files one by one.
+
+- Do not run `git status` or `git diff` on a shared worktree to build the list, and do not send
+  `file_changes` artifacts. Never infer ownership from timestamps, cwd, a branch, or an
+  unrelated dirty file.
+- The list is not a Git diff, a delivery-time snapshot, or proof of exclusive ownership; late
+  synchronization may extend it after delivery. That never blocks or invalidates delivery.
 - **Never revert, restore, or delete file changes from other agents or missions.**
 - A read-only result uses the same delivery command; summarize that no code change was needed.
 
-The optional annotation shape and `--change-rationales-file -` guidance are under **Optional Change Rationales** above.
-
 ## Rules
 
 - Always attach first and always deliver last once you are on a mission.
@@ -473,4 +516,4 @@ The optional annotation shape and `--change-rationales-file -` guidance are unde
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc input through explicit `--*-file -` flags
 
-<!-- version: 0.6.0 -->
+<!-- version: 0.8.0 -->

package/dist/connectors/core/overlord-mission/reference/cli.md

@@ -88,34 +88,60 @@ ovld protocol deliver --session-key <sessionKey> \
 ```
 
 This is the normal delivery shape: a summary is sufficient. The CLI syncs objective-ledger
-evidence independently before the lifecycle transition.
+evidence independently before the lifecycle transition; tracking gaps and sync failures never
+block delivery. Write the summary by behavior or component (outcome, why, verification, and
+limitations); there is no per-file explanation input.
 
-Artifacts, optional change rationales, and a delivery report remain current annotations when
-they add review value. Use `--payload-json` when the full delivery object fits comfortably inline
-(roughly under 8 KB). Larger inline `--*-json` values are rejected; stream them through the
-corresponding `--*-file -` flag.
+Artifacts and a delivery report remain optional annotations when they add review value. Use
+`--payload-json` when the full delivery object fits comfortably inline (roughly under 8 KB).
+Larger inline `--*-json` values are rejected; stream them through the corresponding `--*-file -`
+flag.
 
 If `heartbeat` succeeds but `deliver` or `update` fails, the session is likely fine — retry with the corresponding `--*-file -` flag instead of inline `--*-json`.
 
-### Change ledger health
+### Captured file evidence
 
-Use this only to inspect or troubleshoot objective-ledger synchronization and hook health:
+Read the objective's captured paths once before writing the delivery summary:
 
 ```bash
-ovld protocol changes --mission-id $MISSION_ID
+ovld protocol changes --objective-id $OBJECTIVE_ID            # this checkout's sessions
+ovld protocol objective-changes --objective-id $OBJECTIVE_ID  # synchronized server history
 ```
 
-It may flush pending metadata-only ledger entries for the attached objective, then reports the
-binding, synchronization result, evidence source/quality, and bounded hook health. It does not
-read or diff the worktree, classify files by agent ownership, draft rationales, or gate delivery.
-Native paths normalized by the connector-owned codec as `file.edited` are valid, non-exclusive
-`declared_edit`/`direct` evidence. Codec-normalized read, search, and fetch callbacks are silent
-no-ops. Mutation-capable callbacks without a normalized edit path, plus shell, generic, unknown,
-and unmapped callbacks, report unavailable evidence health.
+`changes` is local-only: it syncs pending ledger entries (failure is advisory) and returns
+`LocalObjectiveChangesDto` with `scope: "local_objective_sessions"`, synced and pending paths
+deduplicated by path, a 200-row cap with pre-cap `total` and `truncated`, and capture and sync
+warnings. `coverage: "unavailable"` means no local session matched, not that nothing changed.
+`objective-changes` (hosted MCP `overlord_changes`) returns `ObjectiveFileChangesDto` with
+`scope: "server_objective"` across every session, resource, and device, but cannot see
+unsynchronized local rows. Neither read diffs the worktree, classifies ownership, or gates
+delivery.
+
+Rows are cumulative objective evidence, including edits later reverted. `source` is
+`declared_edit` (Native: at least one successful native edit callback), `agent_declared`
+(Declared), or `null` (Unknown historical provenance). Native capture appends a path only for a
+codec-normalized edit with a successful outcome; reads, searches, and fetches are silent. Gap
+codes mean capture may be incomplete, not that a file changed: `shell_activity_unverified`
+(shell ran), `outcome_partial` / `outcome_unavailable` (an edit failed partway or its result was
+unknown, so no path was recorded), and `direct_path_unavailable` (an unmappable tool ran).
+Binding warnings distinguish an unbound session, a bound session with no observed callback, and
+unknown (hosted) availability.
+
+When you know you changed files capture missed (shell or heredoc writes, script or generator
+outputs, deletes, and both rename endpoints), declare exactly those on the existing `update` or
+`deliver` call:
 
-For outputs of a generator, migration, or file-writing script that the hook cannot name, an agent
-may add `--paths path/one.ts,path/two.ts` to its existing `update` or `deliver` call. It is
-optional, paths-only metadata; it is never a request to enumerate every changed or opened file.
+```bash
+ovld protocol deliver --session-key <sessionKey> --objective-id $OBJECTIVE_ID \
+  --summary "Narrative: what you did and next steps." \
+  --paths src/generated/schema.ts,docs/old-name.md,docs/new-name.md
+```
+
+Use `--paths-file <path|->` with a JSON string array for long lists or paths containing commas.
+Paths are normalized against the checkout; traversal, symlinks leaving the checkout, ignored
+paths, and Overlord-managed paths are rejected with a reason on stderr and never fail the call.
+Absent targets (deleted or renamed-away files) are valid. Never enumerate every changed or
+opened file, and when unsure, describe the coverage gap in the summary instead of guessing.
 
 ### Shared worktree safety (critical)
 
@@ -132,42 +158,11 @@ uses the same summary-only delivery as every other objective.
 
 Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
 
-## Optional Change Rationales
+## Retired Per-File Inputs
 
-Rationales are optional annotations stored as `change_rationales` rows. Overlord records
-which files an objective changed on its own, so a delivery never requires them and cannot
-fail for lacking them. Supply one only when the reason for a change is not obvious from the
-diff.
-
-Attach them to `update` while working, or to `deliver` at the end. Inline
-`--change-rationales-json` is fine for a few entries; larger arrays are **rejected** — use
-`--change-rationales-file -` and stream JSON on stdin. The same ~8 KB inline limit applies to
-`--payload-json` and other `--*-json` flags.
-
-**Fields per entry:** `filePath`, `label`, `summary`, `why`, `impact` (all strings),
-plus optional `hunks` containing only a `header` string. Use the canonical
-`filePath` spelling. Do not wrap the entry under a `rationale` key. Unknown keys
-discard only that advisory item or hunk with a bounded warning; the last valid
-item wins when a canonical path is repeated.
-
-```bash
-ovld protocol update --session-key <sessionKey> --mission-id $MISSION_ID \
-  --summary "Added retry logic." --phase execute \
-  --change-rationales-json '[{"label":"Add backoff","filePath":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x.","hunks":[{"header":"@@ -22,4 +22,18 @@"}]}]'
-```
-
-For many entries (roughly 5+), stream them through `--change-rationales-file -` to avoid shell quoting failures:
-
-```bash
-ovld protocol deliver --session-key <sessionKey> --mission-id $MISSION_ID \
-  --summary "Narrative: what you did and next steps." \
-  --change-rationales-file - <<'EOF'
-[
-  {"label":"Add backoff","filePath":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x."},
-  {"label":"Update config","filePath":"lib/config.ts","summary":"Added timeout.","why":"Match new defaults.","impact":"Requests time out after 30s."}
-]
-EOF
-```
+`--change-rationales-json|file`, `--changed-files-json|file`, and the `changeRationales` /
+`changedFiles` payload fields are rejected on `update`, `deliver`, and `record-work`. Explain
+changes in the summary and declare missed paths with `--paths` / `--paths-file`.
 
 ## Project Discovery And Mission Creation
 
@@ -183,7 +178,7 @@ When creating missions from within a repository:
 - `add-objectives` uses the same per-item `autoAdvance` field and `--auto-advance` / `--no-auto-advance` mapping.
 - Every objective item on `create`, `prompt`, and `add-objectives` also takes optional `"agent"` and `"model"` (a model requires an agent), and `--objective-agent <id>` / `--objective-model <id>` set the default for items that name no `agent` of their own. Assign the agent on the objectives you are already creating rather than appending a second objective just to name one. `--objective-agent` is distinct from `--agent`, which records creation provenance (and, on `prompt`, the attaching agent).
 - Use `ovld protocol run-queue [--project-id <id|slug|name>|--objective-id <id>|--mission-id <id>] [--queue <id|name>]` to inspect live queues. Entry operations use `queue-objective --objective-id <id> [--queue <id|name>] [--after <queued-entry|objective>|--front|--position <rank>]`, `dequeue-objective --objective-id <id>`, and `reorder-run-queue --queue <id|name> --ordered-entries-json <json>`; they require `execution_request:create`. Queue-definition operations use `create-run-queue`, `update-run-queue`, `delete-run-queue`, and `reorder-project-run-queues`; they require `project:update` and therefore a full-scope token.
-- `record-work` creates exactly one **completed** objective from a single `--objective` (or positional / an `objective` field in `--payload-json`) plus a `--summary` and file-change data — it does not take `--objectives-json`. See [record-work.md](record-work.md).
+- `record-work` creates exactly one **completed** objective from a single `--objective` (or positional / an `objective` field in `--payload-json`) plus a `--summary` and optional `declaredPaths` — it does not take `--objectives-json`. See [record-work.md](record-work.md).
 
 ```bash
 ovld protocol create --project-id <project-id> --agent <agent-identifier> --objectives-json '[{"objective":"Capture follow-up work from this repository"}]'
@@ -211,25 +206,20 @@ ovld protocol update-objective --objective-id <objective-uuid> --auto-advance
 ### Record Completed Work
 
 Record already-finished chat work as a completed review mission in one call — no
-`attach`/`deliver`. Creates a mission with one completed objective, records explicitly supplied
-changed files and optional rationales, lands it in review, and runs the Gemini delivery summary.
+`attach`/`deliver`. Creates a mission with one completed objective, records declared paths as
+Declared evidence, lands it in review, and runs the Gemini delivery summary.
 
 ```bash
 ovld protocol record-work --payload-file - <<'EOF'
 {
   "objective": "Add a CSV export button to the reports page.",
   "summary": "Added a CSV export control and the serializer behind it.",
-  "changeRationales": [
-    { "filePath": "src/reports/export.ts", "label": "CSV serializer",
-      "summary": "New CSV serializer.", "why": "Users need offline reports.",
-      "impact": "Reports can be exported as CSV." }
-  ]
+  "declaredPaths": ["src/reports/export.ts"]
 }
 EOF
 ```
 
-The full submission format, including the `record-work`-only `changedFiles` field and MCP
-equivalent, is in [record-work.md](record-work.md).
+The full submission format, including `declaredPaths` rules and the MCP equivalent, is in [record-work.md](record-work.md).
 
 To inspect project resolution explicitly:
 

package/dist/connectors/core/overlord-mission/reference/context.md

@@ -34,7 +34,7 @@ When a later objective or follow-up must revise a plan, notes, or URL artifact c
 For large artifacts such as planning documents, architecture decisions, research summaries, or design documents: **save the full content as a markdown file in the linked repository, then summarize it in the artifact returned to the mission.**
 
 - Save to a meaningful path in the repository (e.g., `ai/feature-plans/my-feature.md` for feature plans, `docs/decisions/my-decision.md` for architecture decision records).
-- Commit the file as part of the mission's work so it appears in `changeRationales`.
+- Write it with your normal edit tool so native capture lists it among the objective's changed files (declare it with `--paths` if you wrote it from a shell command).
 - Prefer `add-artifact` mid-turn (or a delivery artifact) with a `note` or `decision` type, a concise summary, and the repository file path — not the full document content.
 
 This keeps the mission feed readable while preserving the full document in version control where it can be reviewed, diffed, and referenced later. If that summary artifact already exists on the mission, revise it with `update-artifact` rather than creating another copy.

package/dist/connectors/core/overlord-mission/reference/mcp.md

@@ -6,9 +6,10 @@
 - `discover_project` accepts an explicit project id (`projectId` hosted, `project_id` local shim) or a working directory (`workingDirectory` hosted, `working_directory` local shim). When resolving by directory and a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint` so resource-directory matching prefers the current device.
 - `permission-request` is invoked by connector permission hooks installed by adapter bundles. Agents do not normally call it directly.
 - Execution request tools (`request_execution`, `claim_execution`, `list_execution_requests`, `clear_execution_requests`, `complete_execution_launch`, `fail_execution_launch`) back the local runner queue. Agents normally work missions with `attach`/`update`/`deliver`; runner processes use these queue tools.
-- Change rationales are optional annotations attached to `update` or `deliver` (`--change-rationales-json` / `--change-rationales-file`, or `changeRationales` over MCP) and stored as `change_rationales` rows. Normal delivery requires only a summary; objective-ledger evidence is captured locally and synchronized independently.
+- Normal delivery requires only a summary, written by behavior or component; there is no per-file explanation input, and the retired `changeRationales` / `changedFiles` fields are rejected. `overlord_update_session`, `overlord_deliver_session`, and `overlord_record_work` accept optional `declaredPaths`: a JSON array of repository-relative paths you know you changed that native capture missed, such as script outputs, deletes, and both rename endpoints. They are recorded as Declared evidence and never block the call.
+- `overlord_changes` (hosted MCP) reads one objective's synchronized file evidence across every session, resource, and device (`scope: "server_objective"`, rows capped at 200 with a pre-cap `total` and `truncated`, plus capture warnings). It needs no attached session, mutates nothing, and cannot see unsynchronized local rows; the local `ovld protocol changes --objective-id` read covers this checkout's pending evidence. The route is `POST /api/protocol/objective-changes`.
 - `overlord_create_mission` requires `projectId` for a mission, unless `unassignedToProject: true` deliberately requests an account-owned inbox item; omission of both is rejected. `overlord_create_inbox_item` is also explicit by name.
-- `overlord_record_work` (hosted MCP) and `ovld protocol record-work` (CLI) record already-completed chat work as a single review-column mission with a completed objective, explicitly supplied changed files, optional rationales, and the standard Gemini delivery summary — no `attach`/`deliver`. Both require an explicit project reference. The submission format is in [record-work.md](record-work.md). The route is `POST /api/protocol/record-work`.
+- `overlord_record_work` (hosted MCP) and `ovld protocol record-work` (CLI) record already-completed chat work as a single review-column mission with a completed objective, optional declared paths, and the standard Gemini delivery summary — no `attach`/`deliver`. Both require an explicit project reference. The submission format is in [record-work.md](record-work.md). The route is `POST /api/protocol/record-work`.
 - `overlord_add_artifact` (hosted MCP) and `ovld protocol add-artifact` (CLI) create a mission artifact during a turn without delivering. Required: `type` / `--type`, `label` / `--label`, mission scope (`missionId` / `--mission-id`, or an objective display id as `objectiveId` / `--objective-id`), plus at least one of `contentText` / `--content-text`/`--content-text-file` or `externalUrl` / `--external-url`. Optional `sessionKey` / `--session-key` stamps session/objective provenance; `objectiveId` / `--objective-id` does the same when there is no live session, and the session key wins if both are given. Same service as REST `POST /api/missions/:id/artifacts`. The route is `POST /api/protocol/add-artifact`.
 - `overlord_update_artifact` (hosted MCP) and `ovld protocol update-artifact` (CLI) revise an existing mission artifact's label, Markdown content, and/or HTTP(S) URL in place. Required: `artifactId` / `--artifact-id`, `expectedRevision` / `--expected-revision`, and mission scope (`missionId` / `--mission-id`, or an objective display id as `objectiveId` / `--objective-id`). Provide at least one editable field. No session key is required. Same service as REST `PATCH /api/missions/:id/artifacts/:artifactId`. The route is `POST /api/protocol/update-artifact`.
 - `overlord_delete_missions` / `overlord_delete_objectives` (hosted MCP) and `ovld protocol delete-missions` / `delete-objectives` (CLI) bulk soft-delete one to 100 mission or objective UUID/display-id references atomically. They require `confirm: true` / `--confirm`; before setting it, agents must show the resolved list to the user and receive affirmative approval. A missing, duplicate, deleted, or unauthorized target rejects the entire request. Mission deletion includes live child objectives; objective deletion removes live Run Queue membership.

package/dist/connectors/core/overlord-mission/reference/record-work.md

@@ -5,7 +5,7 @@ just built for the user in a chat app — as a completed Overlord mission. It is
 after-the-fact equivalent of `create` + `attach` + `deliver`, collapsed into one call:
 
 1. Creates a mission with a **single completed objective** matching the work done.
-2. Records explicitly supplied changed files and any optional reviewer annotations.
+2. Records any paths you declare as the objective's Declared file evidence.
 3. Lands the mission in the **review** column.
 4. Runs the delivery through the **standard Gemini delivery summarizer**, so the result
    reads like any other delivered (in-review) mission.
@@ -24,18 +24,7 @@ identical across the CLI (`--payload-file -`) and the hosted MCP tool
   "objective": "What was asked and what you did, phrased as a completed objective (1–3 sentences).",
   "summary": "Reviewer-facing narrative of what changed and why. This is what the PM reads first.",
   "title": "Optional mission title; defaults to a title derived from the objective.",
-  "changeRationales": [
-    {
-      "filePath": "src/widget.ts",   // repository-relative path
-      "label": "Add widget",          // short reviewer title
-      "summary": "New widget module.", // what changed in this file
-      "why": "User asked for a widget.", // why it changed
-      "impact": "Widget now renders on the dashboard." // behavioral impact
-    }
-  ],
-  "changedFiles": [
-    { "filePath": "src/generated.ts", "vcsStatus": "M" }
-  ],
+  "declaredPaths": ["src/widget.ts", "src/generated.ts"], // optional repository-relative paths
   "artifacts": [
     { "type": "next_steps", "label": "Next steps", "content": "…" } // optional
   ]
@@ -48,24 +37,29 @@ identical across the CLI (`--payload-file -`) and the hosted MCP tool
   `--objective`/positional on the CLI; a flag always wins over the envelope.
 - **`summary`** (required) — narrative, not a command list.
 - **`title`** (optional) — omit to derive from the objective.
-- **`changeRationales`** (optional reviewer annotations) — same shape as `deliver`. All
-  five string fields (`filePath`, `label`, `summary`, `why`, `impact`) are required per
-  entry. Use canonical `filePath`; do **not** wrap entries under a `rationale` key.
-- **`changedFiles`** (optional, `record-work` only) — files known to have changed during
-  this completed chat work. Each entry is an object with a canonical repository-relative
-  `filePath` and optional bounded `vcsStatus`; raw strings, absolute paths, and extra fields
-  are rejected. A rationale's `filePath` is recorded automatically, so do not list it twice.
-  Do not infer ownership from a shared-worktree-wide status or diff.
+- **`declaredPaths`** (optional) — the files you know you changed for this work, as a
+  JSON array of canonical repository-relative path strings (deleted files and both
+  endpoints of a rename are valid). There is no native capture for record-work, so every
+  path is recorded with Declared provenance and no resource. Absolute, traversing, and
+  Overlord-managed paths are ignored with a bounded warning and never fail the record. A
+  handful of representative paths is fine; do not infer the list from a shared-worktree
+  status or diff. Explain the change in `summary`: there is no per-file explanation field,
+  and the retired `changeRationales` / `changedFiles` inputs are rejected.
 - **`artifacts`** (optional) — `next_steps`, `test_results`, `migration`, `note`, `url`,
   or `decision`.
 - **`deliveryReport`** (optional) — you may include a `deliveryReport.agentReport`
   (`humanActions`, `tradeoffsMade`, `knownRisks`, `deferredWork`, `assumptions`) just as
-  in `deliver`. Each `deferredWork` item must be a recommended new objective that is not
-  part of this mission (for example a bug discovered here that belongs outside it). Name
-  the component or file involved and say why the work was left. Never list work already
-  covered by this mission's future objectives, leftover slices of the current objective,
-  or human implementation follow-up (those belong in `humanActions`). Use an empty array
-  when nothing qualifies. It improves review visibility but never blocks the record.
+  in `deliver`. Each `deferredWork` item is one recommended objective outside this
+  mission. Be very concise. `title` names the work in an imperative phrase. `change`
+  states only the specific change that is needed. `location` says where to find it in
+  the code: the file, function, component, or command. `doneWhen` states the observable
+  result in one sentence. Do not add instructions on how to do the work, background, or
+  rationale. The operator turns the item into an objective or a mission as written, so it
+  must read as a task, not as a note. All four fields are required (at most 80, 400, 200
+  and 200 characters); a plain string item is rejected with `invalid_input`. Never list
+  work already covered by this mission's future objectives, leftover slices of the
+  current objective, or human implementation follow-up (those belong in `humanActions`).
+  Use an empty array when nothing qualifies. It improves review visibility but never blocks the record.
 
 ## CLI
 
@@ -76,14 +70,7 @@ ovld protocol record-work --payload-file - <<'EOF'
 {
   "objective": "Add a CSV export button to the reports page.",
   "summary": "Added a CSV export control and the serializer behind it.",
-  "changeRationales": [
-    { "filePath": "src/reports/export.ts", "label": "CSV serializer",
-      "summary": "New CSV serializer.", "why": "Users need offline reports.",
-      "impact": "Reports can be exported as CSV." }
-  ],
-  "changedFiles": [
-    { "filePath": "src/reports/generated-schema.ts", "vcsStatus": "M" }
-  ]
+  "declaredPaths": ["src/reports/export.ts", "src/reports/generated-schema.ts"]
 }
 EOF
 ```
@@ -103,14 +90,7 @@ Call `overlord_record_work` with the same fields as first-class arguments
   "projectId": "acme-web",
   "objective": "Add a CSV export button to the reports page.",
   "summary": "Added a CSV export control and the serializer behind it.",
-  "changeRationales": [
-    { "filePath": "src/reports/export.ts", "label": "CSV serializer",
-      "summary": "New CSV serializer.", "why": "Users need offline reports.",
-      "impact": "Reports can be exported as CSV." }
-  ],
-  "changedFiles": [
-    { "filePath": "src/reports/generated-schema.ts", "vcsStatus": "M" }
-  ]
+  "declaredPaths": ["src/reports/export.ts", "src/reports/generated-schema.ts"]
 }
 ```