hermes - 💡(How to fix) Fix Add privacy-safe time tracking reconciliation plugin

Feature Description

Build a reusable, privacy-safe time-tracking reconciliation plugin that proposes project mappings for unassigned time by combining deterministic activity collection, configurable context sources, constrained LLM analysis, deterministic validation, human approval, and an approval-only executor.

The initial provider target can be Timing, but the design should keep provider-specific API code behind an adapter so other time trackers can be supported later.

Motivation

Automatic time trackers often capture rich app/window/domain activity, but project assignment is still noisy. Agents can infer likely clients/projects by cross-referencing activity patterns with recent work context, but LLMs can hallucinate or overstate billable work. The safe product pattern is:

1. collect raw evidence deterministically,
2. ask an LLM only for cited proposals in a strict schema,
3. validate those proposals mechanically,
4. present a human approval report,
5. apply only approved actions via deterministic API calls.

This makes time reconciliation useful for consultants, agencies, and client teams without letting an LLM directly mutate billing history.

Proposed Solution

Add a plugin or packaged workflow tentatively named time_reconciler with the following pipeline:

collect_context -> propose_mappings -> validate_proposals -> approval_report -> apply_approved_actions

Components

1. Provider adapters

Start with a Timing adapter:

• list projects and project hierarchy
• fetch assigned and unassigned activity blocks
• fetch existing manual time entries
• create/update time entries after approval

Design adapter interfaces so other providers can be added without touching the proposal/validation pipeline.

2. Context source adapters

Configurable sources, all optional:

• Hermes session search
• memory provider search, e.g. Honcho if enabled
• local notes / knowledge-base search
• GitHub activity
• calendar events
• Slack or other message search where available

The plugin must never assume any specific user's workspace, clients, Slack channels, notes paths, project names, or memory backend.

3. Privacy / portability guardrails

• No hardcoded personal names, company names, client names, project IDs, domains, channel IDs, or local filesystem paths.
• All provider credentials must come from env/config and should never be serialized into proposal artifacts.
• Proposal artifacts should support redaction of raw titles/domains before export.
• Public examples and tests must use synthetic fixtures only.
• Approval reports should include enough evidence for a human to decide, but must support a redact_sensitive_evidence option.

4. LLM proposal schema

The LLM should only produce structured proposals, e.g.:

{
  "proposals": [
    {
      "source_block_ids": ["block_123"],
      "start": "2026-01-01T13:30:00-05:00",
      "end": "2026-01-01T13:45:00-05:00",
      "duration_seconds": 900,
      "recommended_project_ref": "/projects/example",
      "recommended_project_chain": ["Work", "Example Client", "Development"],
      "title": "Remote infrastructure check",
      "confidence": 0.82,
      "billing_risk": "medium",
      "evidence": ["window title mentions Example Client", "nearby assigned activity matched same project"],
      "counterevidence": ["some idle time detected"],
      "action": "needs_approval"
    }
  ]
}

5. Deterministic validation

Reject or downgrade proposals when:

• project reference does not exist
• proposed duration exceeds source unassigned duration
• proposed entries overlap unexpectedly
• confidence is below configured threshold
• billing status is billable without explicit approval or strong evidence
• the LLM cites no evidence or only weak evidence
• source block was already applied in a previous run

6. Approval workflow

Generate both:

• machine-readable manifest, e.g. proposals.json
• human-readable approval report, e.g. Markdown/Slack-friendly text

Approval should produce a separate approved.json manifest. The executor should consume only this approved manifest and should not re-run inference.

7. Executor

Apply only approved actions through provider adapters. Return created/updated entry IDs and write an audit artifact.

Configuration Sketch

time_reconciler:
  provider: timing
  timing:
    api_key_env: TIMING_API_KEY
  context_sources:
    sessions:
      enabled: true
    memory:
      enabled: true
    notes:
      enabled: false
      paths: []
    github:
      enabled: false
    calendar:
      enabled: false
  privacy:
    redact_sensitive_evidence: true
    persist_raw_activity: false
  proposal:
    min_confidence_for_safe: 0.80
    min_seconds: 60
    round_to_minutes: 1
  execution:
    require_human_approval: true
    default_billing_status: undetermined

Acceptance Criteria

• Provides a reusable adapter interface for time-tracking providers.
• Includes a Timing adapter for projects, activity, entries, and approved entry creation.
• Collects evidence into portable JSON/JSONL artifacts with no secrets.
• Generates strict-schema LLM proposals with evidence and counterevidence.
• Validates proposals deterministically before any approval report is shown.
• Produces a human-readable approval report and a machine-readable proposal manifest.
• Applies only actions present in an explicit approved manifest.
• Includes synthetic fixtures and tests; no real user/client data in tests or docs.
• Documents privacy model, redaction behavior, and how to add new providers/context sources.

Non-goals for v1

• Fully automatic billing mutation without human approval.
• Hardcoded rules for any specific user's clients/projects.
• Permanent app-assignment rule creation unless the provider API supports it and the action is explicitly approved.
• Sharing raw private activity logs outside the local environment.

Security / Privacy Notes

This should be treated as billing-adjacent data. Default posture should be local-first, no raw activity export, no secrets in artifacts, and no LLM-driven writes. The LLM proposes; deterministic code validates and executes only approved actions.