OMP Worklog

OMP Worklog is a Project Time-driven Ruby CLI and OMP plugin for reviewed personal work logs. It reports human/AI observations separately, prepares independent concurrent-project candidates, and files a reviewed daily batch to Harvest after explicit approval. Time-off and ordinary-work commands remain available.

The repository-local knowledge base defines the product direction, domain, architecture, decisions, and QA boundaries. It distinguishes the provider-neutral work-log direction from the current Harvest-specific adapters.

1. Open Harvest ID Developers and create a Personal Access Token for this local tool.

2. Harvest displays the token and the available Harvest account IDs once. Copy the account ID for the account to track time in.

3. Fill the ignored .envrc in this repository:

   export HARVEST_ACCESS_TOKEN="your-personal-access-token"
   export HARVEST_ACCOUNT_ID="your-harvest-account-id"

4. Run direnv allow if you use direnv; otherwise run source .envrc in the shell that starts OMP or the CLI.

Personal Access Tokens are the intended Harvest authentication method for personal scripts. Revoke and replace a token from Harvest ID if it is exposed. Harvest authentication documentation.

omp-worklog time-off FROM TO --project NAME --task NAME [options]
omp-worklog time-off FROM TO --project-id ID --task-id ID [options]
omp-worklog work-entry DATE --project NAME --task NAME --hours HOURS --notes NOTES [options]
omp-worklog work-entry DATE --project-id ID --task-id ID --hours HOURS --notes NOTES [options]

The time-off command creates one 7-hour entry for each Yukon business day in an inclusive range. It skips weekends and observed Yukon holidays by default.

omp-worklog time-off 2026-08-17 2026-08-28 \
  --project 'Time Off - Marlen' \
  --task 'Vacation / PTO' \
  --notes 'regular time off' \
  --dry-run

The default holiday region is ca_yt. Add --holiday-region REGION or set HARVEST_HOLIDAY_REGIONS to include other Holidays regions. business_time calculates business days and holidays supplies observed statutory holidays.

A time-off block never creates weekend entries. When names are supplied, it resolves them from your active personal Harvest assignments, so a Project Manager role is not required.

The omp_worklog_record_time_off OMP tool accepts the same name pair or ID pair. Its optional holidayRegions array adds per-call regions to the configured defaults.

The work-entry command checks for existing or locked entries for its project, task, and date before creating a new duration entry. Use --dry-run to complete that preflight without a write.

/worklog timesheet DATE reads local human_active Project Time evidence and produces one review-only draft for every local project active on that day. It does not call Harvest or require Harvest credentials.

Use --project PROJECT only to restrict the draft to one exact local Project Time project:

/worklog timesheet yesterday
/worklog timesheet yesterday --project wrap

A configured projectTimeMappings destination becomes the draft's Harvest Project and Task. Evidence with no mapping, an ambiguous work item, or an unassigned work item remains visible under its exact local project with Harvest: Review destination; choose the Harvest project and task before submitting. The command first renders date, local project, duration, and Harvest destination on separate lines in a single column, bounded to 22 physical lines. In interactive OMP sessions, a keyed Generating work summary… widget appears while the active model works and is replaced in place by the final summary or unavailable fallback. Summary evidence is ranked by cumulative workstream duration so structured repository and GitHub issue/PR context outweighs fragmented individual prompts. The final generated section contains one to three broad outcome bullets and a suggested Harvest note, remains bounded before display, and keeps the combined result within 30 logical lines. GitHub issue/PR numbers and Jira ticket IDs are extracted as facts, not inferred by the model. harvest_preview_project_time_drafts retains source IDs, source kinds, repository identities, intervals, work-item attribution, and narratives for detailed review. Nothing is submitted automatically.

User stories:

• As a worker preparing a Harvest entry, I see one vertical column containing the date, exact local project, total duration, Harvest project/task or review warning, a short work summary, and a suggested note.
• As a worker waiting for the summary, I see one generation widget replaced in place by the final output.
• As a worker using --project, I see only that exact local project; unrelated projects and excluded records stay hidden.
• As a reviewer, I see broad duration-weighted work outcomes, generated prose marked for review, and only ticket identifiers grounded in selected evidence.
• As an auditor, I use the explicit preview tools when I need source IDs, intervals, repository metadata, raw narratives, or attribution details.

The observable contract is a deterministic block of at most 22 physical lines followed by a generated section of at most six lines, keeping the complete result within 30 logical lines. Every total stacks date, exact local project, aggregate duration, and configured Harvest project/task or Review destination on separate lines. The generated section uses the AI-generated work summary (review before use) heading, one to three concise outcome bullets derived from at most eight duration-ranked evidence records, and a clearly review-marked suggested Harvest note. Generated lines are capped at 100 characters with an ellipsis so one verbose model line cannot consume the screen. In interactive mode, one keyed OMP widget is updated from the generation state to final content; print and RPC modes retain a normal transcript message. The command remains review-only and never writes Harvest.

Type /worklog to discover review, timesheet, stats, plan, and submit. Date aliases are completed contextually. After --project, timesheet completion lists human-active projects; review, stats, and plan also include agent-only projects. Completion preserves exact local project names.

At the end of a workday, run /worklog review. It opens today's worklog inside OMP: edit each project's duration, destination, and factual note, then choose Mark reviewed or Exclude entry. A duration above the automatic candidate also requires Edit adjustment reason. When all retained entries are ready, choose Submit to Harvest and confirm the displayed snapshot. No JSON editing or path copying is required. Use /worklog review yesterday for another day.

Save and close preserves your private draft, including correction reasons, for the next run. Refresh evidence rebuilds the snapshot after confirmation, clears corrections and review state, and retains the prior draft privately. Review does not submit anything until you approve the final confirmation.

/worklog stats 2026-10-05 2026-10-18
/worklog stats today --until 12:00
/worklog plan yesterday
/worklog submit "PATH-PRINTED-BY-PLAN" --dry-run
/worklog submit "PATH-PRINTED-BY-PLAN"

Different projects retain independent candidate durations; overlapping human/agent evidence within one project is counted once. Only same-session gaps within the five-minute response grace may be inferred, and historical progress/blocker state still needs review. Plans are private, unapproved JSON files with required factual notes and reviewer-adjusted durations. The interactive submit asks for one explicit approval, preflights every record, and then files the batch with duplicate and uncertain-outcome protection.

See reviewed concurrent worklogs for the policy, review fields, CLI/tool interfaces, private backups, and recovery. Headless callers can use omp-worklog work-entry-batch [--dry-run] with a reviewed JSON document on stdin; actual writes require approved: true.

Worklog resolves persisted user settings and project overrides through the supported omp plugin config list omp-worklog --json command at initialization, using the OMP project cwd. Project values override user values; explicit factory options override both for programmatic callers and tests. Resolution runs once before commands and tools register; restart or reload the extension after changing settings. A resolution failure reports a diagnostic instead of silently using the wrong destination.

• defaultHours: hours per business day when a time-off tool call omits hours; defaults to 7.
• holidayRegions: comma-separated Holidays regions; defaults to ca_yt.
• command: direct path to the omp-worklog executable.
• projectTimeLogPath: optional path to Project Time v1 evidence; defaults to ~/.omp/project-time/time-log.sqlite. A legacy versioned JSON snapshot is also supported.
• projectTimeMappings: optional JSON mapping of exact local projects to Harvest project/task names; defaults to {}.
• responseGraceMinutes: same-session response-gap inference for review candidates; defaults to 5, with 0 disabling gap inference. This does not certify progress or authorize billing.

The host stores user plugin settings in ~/.omp/plugins/omp-plugins.lock.json and project overrides in .omp/plugin-overrides.json. Back up private configuration outside Git before uninstalling/reinstalling a plugin. Worklog deliberately does not parse these files itself or bypass project precedence.

Configure projectTimeMappings with the recorded OMP Project Time project name as the key:

{
  "Harvest API": { "project": "Internal", "task": "Development" }
}

OMP Worklog reads Project Time's persisted omp-project-time/evidence v1 entries. An absent, unsupported, or malformed ledger produces a no-write diagnostic; run a current Project Time session to create the SQLite ledger before retrying.

omp_worklog_preview_project_time_drafts produces deterministic, copyable Date/Project/Task/Duration blocks from all local human_active evidence in an inclusive date range. Mapped evidence uses its configured Harvest destination; unmapped, ambiguous, and unassigned evidence remains an explicit local-project draft. It preserves source entry IDs, intervals, source kind, repository identity, narratives, work items, and task-attribution provenance. Generated narratives are review evidence, never task identity or a factual Harvest note. The tool reads the local log only; it never calls or mutates Harvest.

Drafts preserve every positive interval using raw milliseconds, even when rounded decimal hours are zero. Exact displayed duration is review evidence, not a Harvest rounding or billable-time policy. Both range endpoints must be real calendar dates.

For independent comparison with manually recorded Harvest entries, follow the private calibration workflow. Do not tune from incomplete baselines or commit personal evidence.

omp_worklog_preview_project_time_transforms emits deterministic JSON for local raw intervals. It accepts an inclusive date range and optional exact repositoryId, project, and sourceKind filters; each matching interval is split by local date and grouped by activity, with missing labels reported as unlabelled. It defaults to human_active and returns the effective top-level sourceKind; selecting agent_turn_elapsed requires an explicit source-kind request. Set applyMappings to create configured Harvest destinations or review-required local destinations for every included group. The output reports groups and draft entries; it never writes Harvest.

Version 0.14.0 is a clean identity cutover. Uninstall the retired harvest-worklog gem and OMP plugin, then install omp-worklog; replace former harvest-worklog CLI and /harvest-worklog command invocations with omp-worklog and /omp-worklog. The retired package, executable, command, tools, module, and settings aliases are not retained.

Version 0.14.3 renames the OMP slash command from /omp-worklog to /worklog; the omp-worklog package identity and CLI executable are unchanged.

• Allow explicitly reviewed duration increases with a required private adjustment reason, without changing the automatic candidate or source evidence.
• Preserve corrections across save/resume and show candidate, reviewed duration, and rationale in the final approval.
• Keep native review, saved-batch validation, and Ruby filing consistent while retaining duplicate and uncertain-outcome protections.

• Keep the time-off tool's numeric schema compatible with Codex requests.
• Continue requiring positive finite hours while accepting small fractional durations.

• Review and submit today's worklog inside OMP with /worklog review [DATE].
• Edit or exclude entries through native dialogs, save/resume private daily drafts, and refresh evidence without losing prior edits.
• Display readable filing outcomes while retaining the existing batch approval and recovery protections.

• Add daily/project human-active and AI elapsed reports with a final-day cutoff.
• Prepare private concurrent-project review batches with within-project deduplication and five-minute same-session response grace.
• File explicitly approved batches with user-scoped preflight, stable identities, private receipts, and safe partial/uncertain-result handling.

• Activate persisted settings through the supported host CLI before registering commands, completion, and tools.
• Honor project override precedence and retain explicit factory-option overrides without parsing host configuration files.

• Preserve saved user settings across the required clean plugin reinstall, without copying project overrides or manifest defaults into user configuration.
• Retain an owner-only recovery snapshot and report its path; abort before uninstalling when settings cannot be exported.

• Preserve short positive durations in mapped and review-required drafts.
• Refresh project-name completion when SQLite commits evidence through its write-ahead log.
• Reject impossible calendar dates in transform ranges.
• Document configuration activation limits, runtime ownership, and private calibration.

Before merging a release PR, self-review its complete diff, address every actionable review comment, and rerun focused QA after fixups. Record the review and QA evidence on the PR. Then merge to main, build and publish the Ruby gem, install the released OMP plugin from GitHub, and verify it:

npm run test:ruby
npm run test:omp
bin/omp-worklog --help
VERSION="$(ruby -Ilib -romp_worklog/version -e 'puts OmpWorklog::VERSION')"
gem build omp-worklog.gemspec
gem push "omp-worklog-${VERSION}.gem"
gem uninstall omp-worklog --all --executables --ignore-dependencies
gem install --clear-sources --source https://rubygems.org omp-worklog --version "$VERSION" --no-document
npm run release
npm run verify:release
omp-worklog --help

npm run release owns the plugin uninstall/force-install mutation, including removal of the retired plugin when present. npm run verify:release never changes the installation: it checks the installed package version, resolved Git revision, and plugin path, then runs the installed JavaScript test suite. It exits after verification; tests alone do not exercise a fresh OMP host.

The release wrapper exports explicit user settings through OMP's configuration CLI from an isolated temporary directory before uninstalling. It saves settings.json in an owner-only recovery directory, prints that path without values, restores settings through the CLI, and verifies equality after installation. Project overrides remain project-scoped; unset defaults stay unset. Keep the reported backup until the release is confirmed. If installation or restoration fails, recover from that private snapshot after resolving the reported phase; do not paste its contents into an issue.

After installation, start a new OMP process and exercise /worklog completion and a timesheet against synthetic local evidence. Verify that a newly committed SQLite project appears without restarting that process. Existing sessions retain startup-loaded extension code and cannot prove the released artifact. Verify a persisted user mapping and then a different project override; an explicit factory-option smoke alone does not prove saved configuration activation.