omnius 1.0.591 → 1.0.592

package/docs/work-orders/hermes-architecture-deltas/06-vision-evidence-routing-ladder/WORKORDER.md

@@ -0,0 +1,199 @@
+# Workorder: Vision Evidence Routing Ladder
+
+## Objective
+
+Build a generic visual evidence router that resolves scoped media reliably and chooses an analysis ladder based on the current request's information need:
+
+1. low-cost visual observation or native model image path when sufficient,
+2. OCR when text extraction is material,
+3. auxiliary vision such as Moondream/full vision when richer object, scene, UI, identity, or ambiguous evidence is needed.
+
+This directly addresses the Telegram failure mode where the vision tool received missing `image` arguments and the agent fell back to unsupported assumptions.
+
+## Problem Statement
+
+Telegram exposes media through scoped chat storage and helper tools, but the model can still call `vision` without a valid `image` parameter. Public prompt text describes a media stack, yet the executable path is distributed across Telegram media resolution, image analysis tool wrappers, OCR, and vision tools.
+
+The desired behavior is not scenario-specific. The router should derive the needed evidence from the user's current request and the available media, then run the lowest sufficient stage and escalate only when the evidence need is not met.
+
+## Existing Code Anchors
+
+Omnius:
+- `packages/cli/src/tui/telegram-bridge.ts:1275` describes the public Telegram vision/media stack.
+- `packages/cli/src/tui/telegram-bridge.ts:16807` builds `telegram_image_analyze`.
+- `packages/cli/src/tui/telegram-bridge.ts:16840` resolves scoped Telegram media.
+- `packages/cli/src/tui/telegram-bridge.ts:16848` calls staged image analysis.
+- `packages/cli/src/tui/telegram-bridge.ts:16949` reports failed image evidence extraction.
+- `packages/cli/src/tui/telegram-bridge.ts:17393` processes media from messages.
+- `packages/execution/src/tools/vision.ts` owns the core vision tool.
+- `packages/execution/src/tools/ocr-image-advanced.ts` owns OCR.
+- `packages/cli/tests/telegram-media-evidence.test.ts` covers media evidence behavior.
+- `packages/execution/tests/vision-action-loop.test.ts` and `packages/execution/tests/ocr-image-advanced.test.ts` are likely execution-side regression homes.
+
+Hermes:
+- `/home/robit/Documents/repositories/hermes-agent/tools/computer_use/vision_routing.py:118` decides whether capture should route to auxiliary vision.
+- `/home/robit/Documents/repositories/hermes-agent/tools/vision_tools.py:527` checks whether providers accept media in tool results.
+- `/home/robit/Documents/repositories/hermes-agent/tools/vision_tools.py:599` checks native vision fast path.
+- `/home/robit/Documents/repositories/hermes-agent/tools/vision_tools.py:797` implements auxiliary vision analysis.
+
+## Target Architecture
+
+Add `packages/execution/src/vision-evidence-router.ts` or `packages/cli/src/tui/telegram-vision-router.ts` if Telegram-specific media scope must remain in CLI.
+
+Suggested contracts:
+
+```ts
+export interface VisualEvidenceRequest {
+  prompt: string;
+  mediaRefs: VisualMediaRef[];
+  surface: "telegram" | "tui" | "api";
+  currentModel?: ModelCapabilitySummary;
+  requestedDetail?: "auto" | "low" | "text" | "full";
+}
+
+export interface VisualEvidencePlan {
+  stages: VisualEvidenceStage[];
+  reason: string;
+}
+
+export type VisualEvidenceStage =
+  | { kind: "resolve_media"; required: true }
+  | { kind: "low_fidelity_observation"; required: boolean }
+  | { kind: "ocr"; required: boolean }
+  | { kind: "auxiliary_vision"; required: boolean; modelPreference?: string };
+```
+
+Evidence output:
+- resolved media path or safe alias,
+- stage outputs,
+- confidence/coverage notes,
+- unresolved fields,
+- final evidence summary for the model.
+
+## Routing Principles
+
+- Media resolution always happens before vision/OCR execution.
+- Missing `image` should be repaired from current scoped media when possible.
+- If multiple recent images exist, ask the model/tool caller to identify which one or use reply-to media first.
+- OCR is selected when text, numbers, labels, UI copy, documents, screenshots with text, or exact wording matters.
+- Auxiliary vision is selected when low-cost observation/OCR cannot answer the claim.
+- The decision can be model-guided, but the router must record why each stage was selected.
+- No hard-coded news/event/person scenario filters.
+
+## Phased Implementation
+
+### Phase 0: Failure Reproduction
+
+Tasks:
+- Add a regression test for Telegram image analysis where the model calls `vision` or `telegram_image_analyze` with no `image` while a replied-to image exists.
+- Add a test for no available image: tool returns a clear actionable error, not a generic missing parameter error.
+
+Completion metrics:
+- Failure is reproduced before fix.
+- Error message names available media aliases when they exist.
+
+### Phase 1: Media Resolution API
+
+Tasks:
+- Extract media resolution into a reusable function:
+  - reply-to image first,
+  - explicit alias/path second,
+  - latest image in current chat third,
+  - otherwise no-media error.
+- Return structured result with provenance:
+  - source message id,
+  - chat/session key,
+  - media kind,
+  - safe alias,
+  - local path hidden from public output.
+
+File-by-file notes:
+- `packages/cli/src/tui/telegram-bridge.ts`: extract from `resolveTelegramScopedMediaPath`.
+- `packages/cli/tests/telegram-media-evidence.test.ts`: add scoped resolution tests.
+
+Completion metrics:
+- Missing `image` argument is auto-filled only from scoped Telegram media.
+- Public responses never expose local paths.
+
+### Phase 2: Evidence Need Decomposition
+
+Tasks:
+- Implement a small generic function that derives a `VisualEvidencePlan` from request text and available media metadata.
+- It can use simple semantic categories, but not scenario-specific topics.
+- If confidence is low, include multiple stages rather than making unsupported assumptions.
+
+Completion metrics:
+- "What text is in this image?" plans OCR.
+- "What is happening in this photo?" plans low observation then auxiliary vision if needed.
+- "Who/what is shown?" plans auxiliary vision when low observation is insufficient.
+- Tests inspect plan stages and reasons.
+
+### Phase 3: Stage Executor
+
+Tasks:
+- Execute planned stages in order.
+- Stop early only if output satisfies the requested evidence need.
+- Normalize outputs into a single evidence packet.
+- Add stage timings and model/tool identifiers.
+
+Completion metrics:
+- OCR output is available to the agent before final answer when text was needed.
+- Auxiliary vision output is available when OCR/low observation is insufficient.
+- Tool result includes evidence provenance and unresolved gaps.
+
+### Phase 4: Tool Integration
+
+Tasks:
+- Update `telegram_image_analyze` to call the router.
+- Update core `vision` tool to require explicit `image`, but offer a Telegram wrapper that can resolve scoped media.
+- Add aliases in `telegram_media_recent` output that teach the model safe media refs.
+- Ensure public prompt describes the router as an evidence ladder, not as local filesystem access.
+
+Completion metrics:
+- Telegram bots no longer see `Missing required parameter(s): image` when a scoped image exists.
+- If no scoped image exists, the error tells the user to send/reply to an image.
+- Core non-Telegram vision remains strict about explicit paths.
+
+### Phase 5: Model Capability Routing
+
+Tasks:
+- If current model can accept image input natively, use native fast path for low-cost observation when supported.
+- Otherwise use auxiliary model configured for vision.
+- Prefer configured local Moondream/full vision when available and suitable.
+- Record the selected route in the evidence packet.
+
+Completion metrics:
+- Tests mock capability true/false and assert stage selection.
+- Fallback to OCR/auxiliary vision is deterministic in tests.
+
+## Required Tests
+
+- Missing image argument repaired from reply-to media.
+- Missing image argument repaired from latest chat image.
+- No image available returns actionable scoped error.
+- OCR selected for text extraction.
+- Auxiliary vision selected for scene/object ambiguity.
+- Native vision fast path selected when model supports media tool results.
+- Public output hides local path.
+- Evidence packet includes stage provenance.
+
+## Rollout Plan
+
+1. Add resolution and tests.
+2. Route Telegram image analysis through resolver.
+3. Add evidence planner and staged executor.
+4. Add model capability routing.
+5. Tighten prompt/tool descriptions after behavior is proven.
+
+## Risks
+
+- Overusing expensive/full vision. Mitigation: low-cost and OCR stages first when sufficient.
+- Exposing local paths in public. Mitigation: structured evidence packet with public-safe aliases.
+- Router becoming heuristic-heavy. Mitigation: restrict rules to evidence modality needs, not scenario content.
+
+## Definition of Done
+
+- Telegram media calls no longer fail with missing `image` when scoped media exists.
+- Visual analysis escalates through documented stages based on evidence need.
+- The agent receives structured evidence before answering.
+- Tests cover no-media, OCR, native vision, and auxiliary vision paths.

package/docs/work-orders/hermes-architecture-deltas/07-durable-multi-agent-kanban/INDEX.md

@@ -0,0 +1,20 @@
+# Durable Multi-Agent Kanban Index
+
+Progress: not started.
+
+Files in this folder:
+- [WORKORDER.md](WORKORDER.md) - Full phased implementation workorder.
+
+Primary Omnius anchors:
+- `packages/orchestrator/src/agenticRunner.ts:1414` - completion hold loop regression tests.
+- `packages/orchestrator/src/agenticRunner.ts:10011` - todo planning protocol.
+- `packages/cli/src/api/task-manager-singleton.ts` - API task management surface.
+- `packages/cli/src/tui/telegram-bridge.ts:13368` - Telegram sub-agent lifecycle.
+
+Primary Hermes anchors:
+- `/home/robit/Documents/repositories/hermes-agent/hermes_cli/kanban_swarm.py:151` - swarm spec.
+- `/home/robit/Documents/repositories/hermes-agent/hermes_cli/kanban_diagnostics.py:326` - hallucinated completion guard.
+- `/home/robit/Documents/repositories/hermes-agent/docs/kanban/multi-gateway.md:9` - single dispatcher ownership.
+
+Completion target:
+- Long or disputed work can be decomposed into durable, inspectable cards with worker/verifier/synthesizer roles and explicit completion evidence.

package/docs/work-orders/hermes-architecture-deltas/07-durable-multi-agent-kanban/WORKORDER.md

@@ -0,0 +1,174 @@
+# Workorder: Durable Multi-Agent Kanban
+
+## Objective
+
+Add a durable multi-agent work board for long-running admin tasks and public disputed factual work. The board should support decomposition, worker assignment, verification, synthesis, diagnostics, and completion evidence without relying on one runner's transient todo list.
+
+## Problem Statement
+
+Omnius has todos and sub-agents, but large tasks still depend on a single runner maintaining context and self-verifying. Hermes added a Kanban-style durable board, swarm worker specs, dispatcher ownership, and diagnostics for hallucinated card completions.
+
+Omnius should adopt the architectural shape where it improves carryover:
+- durable work decomposition,
+- worker/verifier/synthesizer lanes,
+- explicit evidence attached to card completion,
+- diagnostics when workers claim cards that do not exist or lack evidence.
+
+## Existing Code Anchors
+
+Omnius:
+- `packages/orchestrator/src/agenticRunner.ts:10011` builds todo guidance.
+- `packages/orchestrator/src/agenticRunner.ts:1414` covers persistent completion-provenance hold regression tests.
+- `packages/orchestrator/src/completionContract.ts:233` builds completion scenario decomposition.
+- `packages/cli/src/api/task-manager-singleton.ts` is a task management anchor.
+- `packages/cli/src/tui/telegram-bridge.ts:13368` creates Telegram sub-agent state.
+- `packages/execution/src/tools/full-sub-agent.ts` is a likely worker spawning reference.
+
+Hermes:
+- `/home/robit/Documents/repositories/hermes-agent/hermes_cli/kanban_swarm.py:151` builds swarm metadata.
+- `/home/robit/Documents/repositories/hermes-agent/hermes_cli/kanban_swarm.py:164` creates worker-assigned tasks.
+- `/home/robit/Documents/repositories/hermes-agent/hermes_cli/kanban_diagnostics.py:326` handles hallucinated completion.
+- `/home/robit/Documents/repositories/hermes-agent/hermes_cli/kanban_diagnostics.py:520` diagnoses repeated failure loops.
+- `/home/robit/Documents/repositories/hermes-agent/docs/kanban/multi-gateway.md:9` documents single dispatcher ownership.
+
+## Target Architecture
+
+Add an Omnius board under `.omnius/workboards/` with JSONL event log and compact active snapshot.
+
+Entities:
+- `Board`: run/project scope, owner, status, created/updated.
+- `Card`: title, description, lane, assignee, status, dependencies, evidence requirements.
+- `Evidence`: tool result references, files, URLs, messages, verification notes.
+- `Decision`: why card was split, blocked, reassigned, or completed.
+
+Roles:
+- Decomposer: turns a goal into cards and evidence expectations.
+- Worker: executes a card.
+- Verifier: checks evidence and marks card verified or needs changes.
+- Synthesizer: builds final answer from verified cards and unresolved blockers.
+
+Important constraint:
+- The board must not become a hard-coded scenario matrix. Card schemas are generic; card content is generated from the actual request and observations.
+
+## Phased Implementation
+
+### Phase 0: Scope and Data Model
+
+Tasks:
+- Define board/card/evidence JSON schemas.
+- Decide storage path:
+  - `.omnius/workboards/<run-id>/events.jsonl`
+  - `.omnius/workboards/<run-id>/active.json`
+- Add pure model tests for event replay and status transitions.
+
+Completion metrics:
+- Event replay reconstructs active board.
+- Invalid transition is rejected.
+- Evidence attachment is required before verified completion.
+
+### Phase 1: Board Tools
+
+Tasks:
+- Add execution tools:
+  - `workboard_create`
+  - `workboard_add_card`
+  - `workboard_update_card`
+  - `workboard_attach_evidence`
+  - `workboard_complete_card`
+  - `workboard_show`
+- Keep tools generic and run-scoped by default.
+
+File-by-file notes:
+- `packages/execution/src/tools/workboard.ts`: new tool module.
+- `packages/execution/src/tools/index.ts` or manifest registry: register tools.
+- `packages/execution/tests/workboard.test.ts`: model/tool tests.
+
+Completion metrics:
+- Tools mutate only the scoped board.
+- Completion without evidence returns structured failure.
+- Board show is compact enough for model context.
+
+### Phase 2: Runner Integration
+
+Tasks:
+- For long admin runs, expose board tools and inject a compact board status.
+- Keep normal simple tasks on existing todo path unless the agent chooses board decomposition.
+- Add an option to create a board at run start for admin tasks above a complexity threshold selected by the model or user, not by scenario keywords.
+
+Completion metrics:
+- Simple tasks are not forced into board flow.
+- Long tasks can create board and survive compaction.
+- Board state appears in completion critic context.
+
+### Phase 3: Worker and Verifier Roles
+
+Tasks:
+- Add worker prompt templates for a single card.
+- Add verifier prompt template that reviews card evidence.
+- Ensure worker completion cannot mark card verified directly unless policy allows.
+- Add synthesizer prompt that composes final answer only from verified cards and named blockers.
+
+Completion metrics:
+- Worker can complete card with evidence.
+- Verifier can request changes with specific missing evidence.
+- Synthesizer refuses to claim unverified cards as done.
+
+### Phase 4: Diagnostics
+
+Tasks:
+- Add diagnostics similar to Hermes:
+  - card id not found,
+  - repeated worker failure,
+  - assignee unavailable,
+  - completion claim without evidence,
+  - dependency blocked.
+- Add `/workboard diagnostics` or API endpoint.
+
+Completion metrics:
+- A hallucinated card id is caught and reported.
+- Repeated failures produce suggested next actions.
+- Diagnostics do not auto-complete blocked work.
+
+### Phase 5: Telegram/Public Use
+
+Tasks:
+- Public group disputed facts can optionally create a small board when scrutiny is strict and the agent declares the need.
+- Board details remain internal unless the final answer intentionally summarizes sources/evidence.
+- Admin can inspect board via Telegram DM or TUI.
+
+Completion metrics:
+- Public answers remain concise.
+- Admin can inspect board state.
+- Public strict scrutiny can use board evidence without leaking internal paths.
+
+## Required Tests
+
+- Board event replay and compaction.
+- Card cannot verify without evidence.
+- Worker completion attaches evidence.
+- Verifier request_changes keeps card open.
+- Synthesizer excludes unverified cards.
+- Hallucinated card id diagnostic.
+- Repeated worker failure diagnostic.
+- Runner includes board status in critic context.
+
+## Rollout Plan
+
+1. Add board storage and tools.
+2. Add optional admin-run integration.
+3. Add verifier/synthesizer roles.
+4. Add diagnostics.
+5. Add public strict-scrutiny integration.
+
+## Risks
+
+- Adds overhead to simple tasks. Mitigation: optional and model/user-selected.
+- Creates another planning surface beside todos. Mitigation: board is for durable multi-agent work; todos remain lightweight.
+- Worker self-certification. Mitigation: verifier lane and evidence-required transitions.
+
+## Definition of Done
+
+- Durable board state survives runner compaction and process restarts.
+- Cards require evidence for verified completion.
+- Diagnostics catch hallucinated or unsupported completion.
+- Runner and critic can consume board state generically.

package/docs/work-orders/hermes-architecture-deltas/08-completion-critic-reconciliation-ledger/INDEX.md

@@ -0,0 +1,22 @@
+# Completion Critic Reconciliation Ledger Index
+
+Progress: not started.
+
+Files in this folder:
+- [WORKORDER.md](WORKORDER.md) - Full phased implementation workorder.
+
+Primary Omnius anchors:
+- `packages/orchestrator/src/completionContract.ts:128` - generic completion contract inference.
+- `packages/orchestrator/src/completionContract.ts:233` - completion meta-decomposition.
+- `packages/orchestrator/src/backward-pass-critic.ts:188` - reconciliation packet rendering.
+- `packages/orchestrator/src/agenticRunner.ts:3684` - critic evidence collection.
+- `packages/orchestrator/src/agenticRunner.ts:3729` - review reconciliation packet.
+- `packages/orchestrator/src/agenticRunner.ts:15748` - final run status selection.
+
+Primary Hermes anchors:
+- `/home/robit/Documents/repositories/hermes-agent/agent/tool_result_classification.py` - tool-result classification reference.
+- `/home/robit/Documents/repositories/hermes-agent/tools/tool_result_storage.py:122` - persisted tool-result storage.
+- `/home/robit/Documents/repositories/hermes-agent/agent/background_review.py` - background review reference.
+
+Completion target:
+- Completion review is driven by a durable claim/evidence ledger and critic reconciliation packets, not by optional model wording or hard-coded scenario profiles.

package/docs/work-orders/hermes-architecture-deltas/08-completion-critic-reconciliation-ledger/WORKORDER.md

@@ -0,0 +1,226 @@
+# Workorder: Completion Critic Reconciliation Ledger
+
+## Objective
+
+Convert completion verification into a durable claim/evidence ledger. The critic must receive:
+- proposed final claims,
+- evidence observed before the critique,
+- prior critique feedback,
+- evidence observed after the critique,
+- unresolved loops and failed observations,
+- final status constraints.
+
+The system must block unsupported success claims but avoid unbounded loops by ending as `incomplete_verification` when repeated attempts cannot satisfy the ledger.
+
+## Problem Statement
+
+Recent work improved completion contracts and critic reconciliation, but the architecture still needs a durable source of truth. Evidence currently flows through in-memory tool call logs and prompt packets. The next step is to make claim/evidence state explicit so the critic and renderer cannot drift apart.
+
+The design must not use shortcut wording or scenario-specific keyword lists. It should derive completion criteria from the user request, proposed summary, and observed data.
+
+## Existing Code Anchors
+
+Omnius:
+- `packages/orchestrator/src/completionContract.ts:128` creates generic completion contracts.
+- `packages/orchestrator/src/completionContract.ts:233` builds completion scenario decomposition.
+- `packages/orchestrator/src/completionContract.ts:280` instructs reviewer to invent a situation-specific scenario from request and observations.
+- `packages/orchestrator/src/backward-pass-critic.ts:188` renders reconciliation packets.
+- `packages/orchestrator/src/backward-pass-critic.ts:224` tells critic how to compare prior critique and new evidence.
+- `packages/orchestrator/src/agenticRunner.ts:3684` collects critic tool evidence.
+- `packages/orchestrator/src/agenticRunner.ts:3729` builds `reviewReconciliation`.
+- `packages/orchestrator/src/agenticRunner.ts:3816` handles request_changes or blocked.
+- `packages/orchestrator/src/agenticRunner.ts:15748` selects final run status.
+- `packages/orchestrator/tests/agenticRunner.test.ts:1418` tests persistent provenance hold ending as incomplete verification.
+- `packages/orchestrator/tests/completionContract.test.ts:117` tests incomplete verification contract text.
+
+Hermes:
+- `/home/robit/Documents/repositories/hermes-agent/agent/tool_result_classification.py` classifies tool result significance.
+- `/home/robit/Documents/repositories/hermes-agent/tools/tool_result_storage.py:122` persists tool results.
+- `/home/robit/Documents/repositories/hermes-agent/agent/background_review.py` provides background review reference patterns.
+
+## Target Architecture
+
+Add a run-local ledger:
+
+```ts
+interface CompletionLedger {
+  runId: string;
+  goal: string;
+  createdAtIso: string;
+  updatedAtIso: string;
+  proposedClaims: CompletionClaim[];
+  evidence: CompletionEvidence[];
+  critiques: CompletionCritiqueRecord[];
+  unresolved: CompletionUnresolvedItem[];
+  status: "open" | "approved" | "request_changes" | "blocked" | "incomplete_verification";
+}
+
+interface CompletionClaim {
+  id: string;
+  text: string;
+  source: "task_complete_summary" | "assistant_visible_text" | "derived";
+  materiality: "low" | "medium" | "high";
+  evidenceRequirement: string;
+  evidenceIds: string[];
+  status: "supported" | "unsupported" | "contradicted" | "unverified" | "blocked";
+}
+
+interface CompletionEvidence {
+  id: string;
+  kind: "tool_result" | "file_change" | "delivery_result" | "runtime_observation" | "human_input" | "critic_feedback";
+  observedAtIso: string;
+  toolName?: string;
+  success?: boolean;
+  summary: string;
+  rawRef?: string;
+}
+```
+
+Storage:
+- `.omnius/completion-ledgers/<run-id>.json`
+- append-only JSONL optional for recovery.
+
+## Phased Implementation
+
+### Phase 0: Current Behavior Tests
+
+Tasks:
+- Add tests for:
+  - request_changes blocks completion and loops,
+  - evidence after request_changes is present in next critic prompt,
+  - blocked critic ends as incomplete verification,
+  - repeated holds end as incomplete verification, not completed,
+  - simple public Telegram task still completes when guard disabled.
+
+Completion metrics:
+- Tests lock the current repaired behavior before ledger extraction.
+
+### Phase 1: Ledger Data Model
+
+Tasks:
+- Add `completionLedger.ts` with pure functions:
+  - `createCompletionLedger`
+  - `recordCompletionEvidence`
+  - `deriveClaimsFromProposedText`
+  - `reconcileClaimsWithEvidence`
+  - `recordCritique`
+  - `buildCriticPacketFromLedger`
+- Use generic claim extraction prompts or deterministic scaffolding. Do not encode scenario-specific evidence profiles.
+
+File-by-file notes:
+- `packages/orchestrator/src/completionLedger.ts`: pure model and serializer.
+- `packages/orchestrator/tests/completionLedger.test.ts`: model tests.
+
+Completion metrics:
+- Claims and evidence can be recorded and serialized.
+- Reconciliation packet can be produced without an `AgenticRunner` instance.
+
+### Phase 2: Evidence Ingestion
+
+Tasks:
+- Convert tool call log entries into ledger evidence as tools finish.
+- Record mutated files and delivery results.
+- Record failed tool results, not only successful evidence.
+- Preserve evidence ids in typed run events if the typed event stream workorder has landed.
+
+Completion metrics:
+- Ledger contains shell/API/browser/delivery evidence with success flags.
+- Failed observations are visible to critic.
+- Evidence after prior critique is distinguishable by timestamp or sequence.
+
+### Phase 3: Claim Extraction and Scenario Decomposition
+
+Tasks:
+- When `task_complete` is attempted, derive claims from:
+  - task_complete summary,
+  - visible assistant answer,
+  - original user request,
+  - open todos/board cards.
+- Reuse `buildCompletionScenarioDecomposition`, but make it consume ledger evidence.
+- Store generated decomposition in the ledger for audit.
+
+Completion metrics:
+- Completion scenario is generated from actual claims and observations.
+- Unsupported claims are named as unverified/blocked instead of silently ignored.
+- Unit tests use different task domains without hard-coded scenario branches.
+
+### Phase 4: Critic Packet and Re-review
+
+Tasks:
+- Build critic prompt from ledger:
+  - all material claims,
+  - evidence mapped to each claim,
+  - prior critique,
+  - evidence recorded after prior critique,
+  - unresolved loops.
+- On `request_changes`, store critique and feedback.
+- On next completion attempt, include reconciliation packet.
+- If new evidence resolves the prior critique, critic prompt must explicitly tell critic not to repeat resolved objections.
+
+Completion metrics:
+- Test critic prompt includes prior critique and post-critique evidence.
+- Test resolved evidence appears under the right prior critique.
+- Test no evidence after critique is clearly represented.
+
+### Phase 5: Terminal State Discipline
+
+Tasks:
+- Only `approve` can set `completed=true`.
+- `request_changes` continues unless cycle budget is exhausted.
+- `blocked` sets `incomplete_verification`.
+- Cycle exhaustion sets `incomplete_verification`, never `completed`.
+- Renderer receives status separately from human-facing summary.
+
+Completion metrics:
+- `AgenticResult.status` is accurate.
+- Telegram admin wrapper refuses "completed" for `incomplete_verification`.
+- Public simple tasks still complete when configured fast.
+
+### Phase 6: User-Facing Provenance Summary
+
+Tasks:
+- Admin final response sections:
+  - Done,
+  - Verified,
+  - Not verified / blocked,
+  - Evidence.
+- Public strict mode can cite evidence compactly without exposing internals.
+- TUI can show ledger path for inspection.
+
+Completion metrics:
+- Admin final text includes verified and unverified sections.
+- Ledger file path appears in TUI/admin diagnostics, not normal public chat.
+
+## Required Tests
+
+- Ledger serializes and replays.
+- Claim extraction handles unrelated task domains without scenario keyword logic.
+- Evidence map attaches tool results to proposed claims.
+- Critic prompt includes prior critique and evidence since prior critique.
+- Request_changes blocks completion.
+- Blocked critic yields `incomplete_verification`.
+- Cycle exhaustion yields `incomplete_verification`.
+- Telegram admin does not render incomplete verification as completed.
+- Public fast simple task still reaches task_complete.
+
+## Rollout Plan
+
+1. Add ledger pure model and tests.
+2. Record evidence into ledger while preserving current critic behavior.
+3. Build critic packets from ledger.
+4. Use ledger for final status and admin provenance rendering.
+5. Remove duplicate in-memory-only evidence paths.
+
+## Risks
+
+- Ledger bloat. Mitigation: store raw refs and compact summaries, not full large outputs.
+- Critic over-strictness. Mitigation: materiality, cycle budget, and incomplete verification terminal status.
+- Reward-hacking through claim wording. Mitigation: derive claims from visible answer and task summary, not only self-declared fields.
+
+## Definition of Done
+
+- Completion verification has a durable ledger per run.
+- Critic receives a complete reconciliation packet on re-review.
+- Unsupported success claims cannot complete.
+- Repeated unresolved holds terminate as incomplete verification.
+- Tests prove simple Telegram tasks still complete under fast public mode.