logwork-cli 1.0.0 → 1.1.1

package/README.md

@@ -30,16 +30,26 @@ logwork setup
 
 ## Upgrading from logwork-helper
 
-The package was renamed from `logwork-helper` to `logwork-cli`, and the `logwork-helper` command no longer exists. To upgrade:
+The package was renamed from `logwork-helper` to `logwork-cli`, and the `logwork-helper` command no longer exists. Both packages install a `logwork` command, so remove the old one first (otherwise npm stops with `EEXIST`):
 
 ```bash
+npm uninstall -g logwork-helper
 npm install -g logwork-cli
 logwork setup
 ```
 
 Most of the move is automatic:
 
-- **Old global package:** `logwork setup` removes the global `logwork-helper` package, so its `logwork` command does not conflict with the new one.
+- **Old global package:** if it is still installed, `logwork setup` removes the global `logwork-helper` package before linking. You can also run `npx logwork-cli@latest setup` without uninstalling first.
+- **`EEXIST ... bin/logwork` even after uninstalling:** the old package was linked from `~/.logwork-helper`. If that folder was deleted first, `npm uninstall` cannot remove its links. Remove the broken links, then install again:
+
+  ```bash
+  P="$(npm prefix -g)"
+  rm -f "$P/bin/logwork" "$P"/bin/logwork-helper* "$P/lib/node_modules/logwork-helper"
+  npm install -g logwork-cli && logwork setup
+  ```
+
+  `npx logwork-cli@latest setup` also removes those broken links (macOS).
 - **Local state:** on the first run, settings, project mappings, drafts, apply history and the reminder config are copied from `~/.logwork-helper` to `~/.logwork-cli`. The old directory is left in place.
 - **Login sessions:** your RO and Jira sessions are copied from the old Keychain / Credential Manager entry (`logwork-helper`) to the new one (`logwork-cli`), so you do not need to log in again.
 - **Repo mappings:** a repo that has `.logwork-helper.json` keeps using it until a `.logwork.json` exists.
@@ -67,12 +77,14 @@ Sessions are stored in macOS Keychain or Windows Credential Manager. The default
 ```text
 logwork                 Open the terminal UI
 logwork query [period]  Booked vs logged hours with entry ids (today, yesterday, this-week, last-week, this-month, last-month)
+logwork commits [period] Draft logwork lines from your git commits (--repo, --author)
 logwork quick [-m text] Log one entry for today with guided prompts
 logwork edit <id> ...   Change an existing RO entry (replaces it)
 logwork delete <id>     Delete a submitted or approved RO entry
 logwork reconcile       Compare RO and Jira hours by day (read-only)
 logwork history         Local apply history
 logwork login|logout|status [ro|jira]
+logwork skill install   Install the AI agent skill (Claude Code, Codex)
 logwork setup           Install the runtime and print MCP configs
 logwork mcp             Run the MCP stdio server (used by IDE configs)
 logwork reminder ...    Weekday logwork reminder
@@ -82,6 +94,47 @@ logwork doctor          Write a sanitized diagnostics report
 
 Add `--help` to any command for its options.
 
+## Log Work From Your Commits
+
+Most logwork is the work you committed. logwork turns your commits into draft lines, and the RO booking decides how many hours there are to fill.
+
+```bash
+logwork commits yesterday
+logwork commits this-week --repo ~/code/portal --repo ~/code/api
+```
+
+How the draft is built:
+
+- **Which commits:** your own (`git config user.email`, or `--author`) on every local and remote branch. Stashes and merge commits are skipped.
+- **Grouping:** per day, by repo + ticket key + kind of work.
+- **Worklog task:** chosen from the kind of work.
+
+  | Commit | Worklog task |
+  |---|---|
+  | `feat` | Feature Development |
+  | `fix`, hotfix | Bug Fix |
+  | `refactor`, `perf`, review | Code Review & Refactoring |
+  | `test` | Testing Activities |
+  | `ci`, `build`, release, deploy | Deployment & Release |
+  | `docs`, design | Requirements & Design |
+  | `chore` | Other Activities |
+
+  Conventional prefixes are used first, then keywords in the subject.
+- **Hours:** each day's RO remaining time (booked − logged, per project) is split across the groups in 0.5h steps, weighted by commits and lines changed. Days without a booking get 0h. Without RO access, a weekday counts as 8h.
+
+Nothing is written. Paste the draft into `/logwork`, or let your AI agent use it.
+
+For agents:
+- **MCP tool `draft_from_commits`** returns the same draft as `draftText`.
+- **MCP prompt `log_from_commits`** gives an agent the full procedure:
+  1. find gaps with `get_logwork`;
+  2. draft from commits;
+  3. check task names with `list_tasks`;
+  4. rewrite vague descriptions;
+  5. stay within booked hours;
+  6. get your approval, then `log_work`.
+- **Claude Code / Codex:** `logwork skill install` installs the same procedure as a skill, in `~/.claude/skills/logwork` and `~/.codex/skills/logwork`. For other agents, `logwork skill` prints it so you can paste it into your rules.
+
 ## Logwork Line Format
 
 Every Resource Optimiser entry has a **worklog task** and a free-text **description**. The worklog task is an RO catalog item such as `Feature Development` or `Code Review & Refactoring`. Write each line as:
@@ -154,7 +207,7 @@ claude mcp add --transport stdio logwork -- node ~/.logwork-cli/bin/logwork.mjs
 
 Restart or reload the IDE's MCP tools after saving.
 
-The server exposes 15 tools. It also sends `instructions` covering the approval rules, the line format and the recommended call order. Every write is **two calls to the same tool**:
+The server exposes 16 tools and one prompt (`log_from_commits`). It also sends `instructions` covering the approval rules, the line format and the recommended call order. Every write is **two calls to the same tool**:
 1. Call the tool without `confirm`. It returns a preview with a `batchId` or `previewId` and a summary.
 2. After the user approves, call the same tool again with only that id and `confirm: true`.
 

package/RELEASE.md

@@ -67,7 +67,7 @@ The gate must pass all of the following:
 - Confirm the printed MCP config uses server name `logwork` and `node ~/.logwork-cli/bin/logwork.mjs mcp`.
 - Run `logwork --help` and `logwork --version`.
 - Run `logwork update check --force` against the published npm version.
-- Run `logwork mcp` through an MCP client smoke test and confirm it lists the 15 tools (`get_logwork`, `list_projects`, `list_tasks`, `log_work`, `edit_entry`, `resubmit_entry`, `delete_entry`, `log_jira_work`, `get_jira_issue`, `reconcile`, `get_history`, `map_project`, `login`, `reminder`, `update`).
+- Run `logwork mcp` through an MCP client smoke test and confirm it lists the 16 tools (`get_logwork`, `draft_from_commits`, `list_projects`, `list_tasks`, `log_work`, `edit_entry`, `resubmit_entry`, `delete_entry`, `log_jira_work`, `get_jira_issue`, `reconcile`, `get_history`, `map_project`, `login`, `reminder`, `update`).
 - Confirm the `update` tool requires `confirm: true` for `action: "install"`, and `reconcile` takes preset periods only with no credential or confirmation fields.
 - Run `logwork reconcile this-week` and confirm it reports RO/Jira daily totals without writing either system.
 - On a machine with an older `logwork-helper` install, confirm the first run copies state to `~/.logwork-cli` and `logwork status` shows the existing session without a new login.

package/bin/logwork.mjs

@@ -10,6 +10,7 @@ import { readPackageVersion } from '../lib/package-info.mjs';
 //   logwork mcp           -> MCP stdio server for IDEs and agent CLIs
 export const COMMANDS = [
   { name: 'query', usage: 'query [today|yesterday|this-week|last-week|this-month|last-month] [--json]', summary: 'Show booked vs logged hours with entry ids', load: () => import('../commands/query.mjs'), fn: 'run' },
+  { name: 'commits', usage: 'commits [period] [--repo path]... [--author email]', summary: 'Draft logwork lines from your git commits', load: () => import('../commands/commits.mjs'), fn: 'run' },
   { name: 'quick', usage: 'quick [-m "what you did"]', summary: 'Log one entry for today with guided prompts', load: () => import('../commands/quick.mjs'), fn: 'run' },
   { name: 'edit', usage: 'edit <id> [--hours h] [--task name|#id] [--desc text] [--type type]', summary: 'Change an existing RO entry (replaces it)', load: () => import('../commands/edit.mjs'), fn: 'runRoEditCommand' },
   { name: 'delete', usage: 'delete <id>', summary: 'Delete a submitted or approved RO entry', load: () => import('../commands/delete.mjs'), fn: 'runRoDeleteCommand' },
@@ -18,6 +19,7 @@ export const COMMANDS = [
   { name: 'login', usage: 'login [ro|jira] [--base-url url]', summary: 'Log in to Resource Optimiser (default) or Jira', load: () => import('../commands/auth.mjs'), fn: 'runLogin' },
   { name: 'logout', usage: 'logout [ro|jira]', summary: 'Remove the stored RO (default) or Jira session', load: () => import('../commands/auth.mjs'), fn: 'runLogout' },
   { name: 'status', usage: 'status', summary: 'Show RO and Jira login status', load: () => import('../commands/auth.mjs'), fn: 'runStatus' },
+  { name: 'skill', usage: 'skill [print|install] [--target claude|codex|all]', summary: 'Print or install the AI agent skill for logging from commits', load: () => import('../commands/skill.mjs'), fn: 'run' },
   { name: 'setup', usage: 'setup [--login|--no-login]', summary: 'Install the runtime and print MCP configs', load: () => import('../commands/setup.mjs'), fn: 'run' },
   { name: 'mcp', usage: 'mcp', summary: 'Run the MCP stdio server (used by IDE configs)', load: () => import('../lib/mcp-server.mjs'), fn: 'startMcpServer' },
   { name: 'reminder', usage: 'reminder enable|disable|status|test', summary: 'Manage the weekday logwork reminder', load: () => import('../commands/reminder.mjs'), fn: 'runReminderCli' },
@@ -75,6 +77,7 @@ Examples:
   logwork setup
   logwork login
   logwork query this-week
+  logwork commits yesterday --repo ~/code/app
   logwork quick -m "Fix login bug (SCB-12)"
   logwork edit 304032 --task "Bug Fix" --desc "Fix date picker timezone (SAP-42)"
 

package/commands/commits.mjs

@@ -0,0 +1,82 @@
+import { draftLogworkFromCommits } from '../lib/commit-workflow.mjs';
+import { normalizeReconciliationPeriod } from '../lib/reconciliation-workflow.mjs';
+
+// `logwork commits [period] [--repo path]... [--author x] [--no-bookings] [--json]`:
+// turn your git commits into a logwork draft. Read-only.
+export function parseCommitsArgs(args = []) {
+  const options = { period: 'today', repos: [], author: undefined, useBookings: true, json: false, help: false };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '--no-bookings') {
+      options.useBookings = false;
+    } else if (arg === '--repo' || arg === '--author') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`${arg} requires a value.`);
+      }
+      if (arg === '--repo') {
+        options.repos.push(value);
+      } else {
+        options.author = value;
+      }
+      index += 1;
+    } else if (arg.startsWith('--repo=')) {
+      options.repos.push(arg.slice('--repo='.length));
+    } else if (arg.startsWith('--author=')) {
+      options.author = arg.slice('--author='.length);
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown commits option: ${arg}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (positional.length > 1) {
+    throw new Error('commits accepts exactly one preset period.');
+  }
+  if (positional[0]) {
+    options.period = normalizeReconciliationPeriod(positional[0]);
+  }
+  return options;
+}
+
+export async function run(args = [], { draft = draftLogworkFromCommits, print = console.log } = {}) {
+  const options = parseCommitsArgs(args);
+  if (options.help) {
+    print(formatCommitsHelp());
+    return 0;
+  }
+  const result = await draft({
+    period: options.period,
+    repos: options.repos,
+    author: options.author,
+    useBookings: options.useBookings
+  });
+  print(options.json ? JSON.stringify(result, null, 2) : result.summary);
+  return 0;
+}
+
+export function formatCommitsHelp() {
+  return `Usage:
+  logwork commits [today|yesterday|this-week|last-week|this-month|last-month]
+                  [--repo <path>]... [--author <email>] [--no-bookings] [--json]
+
+Reads your commits (all branches, your git user.email) from each repo (default:
+the current directory) and drafts logwork lines:
+  +<hours> <worklog task> | <description>
+
+- Commits are grouped per day by repo, ticket key and kind of work.
+- The kind of work picks the worklog task: feat -> Feature Development,
+  fix -> Bug Fix, refactor/perf/review -> Code Review & Refactoring,
+  test -> Testing Activities, ci/build/release -> Deployment & Release,
+  docs/design -> Requirements & Design, chore -> Other Activities.
+- Hours split the day's RO remaining time (booked - logged) by how much work
+  each group holds. With --no-bookings or without login, a weekday is 8h.
+
+Nothing is written. Review the draft, then paste it into /logwork or give it
+to your AI agent (log_work).`;
+}

package/commands/setup.mjs

@@ -4,6 +4,7 @@ import { delimiter, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { redactText } from '../lib/auth-redaction.mjs';
 import { credentialStoreLabel } from '../lib/credential-store.mjs';
+import { npmInvocation } from '../lib/npm-command.mjs';
 import { helperHome } from '../lib/paths.mjs';
 import {
   MCP_SERVER_NAME,
@@ -59,7 +60,7 @@ export async function installUserRuntime({
   sourceDir,
   targetDir,
   mkdirFn = fs.mkdir,
-  copyFn = copyDirectory,
+  copyFn = copyRuntimeFiles,
   cleanupFn = sanitizeRuntimeMetadata,
   installFn = installDependencies,
   linkFn = linkGlobalBinaries,
@@ -103,6 +104,40 @@ async function refreshReminderSchedule(targetDir) {
   }
 }
 
+// Copies only what the npm package ships (package.json "files", plus the
+// manifest and lockfile). The target is also the state directory, so a git
+// checkout's .env files, tests, archives or a repo-scope .logwork.json must
+// never land there.
+export async function copyRuntimeFiles(sourceDir, targetDir) {
+  const manifest = JSON.parse(await fs.readFile(join(sourceDir, 'package.json'), 'utf8'));
+  const listed = Array.isArray(manifest.files) ? manifest.files : [];
+  const names = ['package.json', 'package-lock.json', 'npm-shrinkwrap.json', ...listed.map((item) => String(item).replace(/[\\/]+$/, ''))];
+  for (const name of [...new Set(names)]) {
+    const sourcePath = join(sourceDir, name);
+    let stat;
+    try {
+      stat = await fs.stat(sourcePath);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        // A lockfile from an earlier install that no longer matches this
+        // package.json would make `npm ci` fail; let npm install write a new one.
+        if (name === 'package-lock.json') {
+          await fs.rm(join(targetDir, name), { force: true });
+        }
+        continue;
+      }
+      throw error;
+    }
+    if (stat.isDirectory()) {
+      await fs.mkdir(join(targetDir, name), { recursive: true });
+      await copyDirectory(sourcePath, targetDir, sourceDir);
+    } else {
+      await fs.mkdir(dirname(join(targetDir, name)), { recursive: true });
+      await fs.copyFile(sourcePath, join(targetDir, name));
+    }
+  }
+}
+
 async function copyDirectory(sourceDir, targetDir, rootDir) {
   const entries = await fs.readdir(sourceDir, { withFileTypes: true });
 
@@ -139,7 +174,8 @@ function installDependencies(targetDir) {
 
 function runCommand(command, args, options = {}) {
   return new Promise((resolveValue, reject) => {
-    const child = spawn(command, args, options);
+    const invocation = command === 'npm' ? npmInvocation(args) : { command, args, shell: false };
+    const child = spawn(invocation.command, invocation.args, { ...options, shell: invocation.shell });
 
     child.on('error', reject);
     child.on('close', (code) => {
@@ -243,9 +279,73 @@ function isStaleSelfDependency(value) {
   return typeof value === 'string' && /^file:.*logwork-(helper|cli).*\.tgz$/i.test(value);
 }
 
+const LEGACY_GLOBAL_LINKS = [
+  'bin/logwork',
+  'bin/logwork-helper',
+  'bin/logwork-helper-install',
+  'bin/logwork-helper-manual',
+  'bin/logwork-helper-mcp',
+  'bin/logwork-helper-setup-user',
+  'lib/node_modules/logwork-helper'
+];
+
+// The old package was installed with `npm link` from ~/.logwork-helper. When
+// that folder is deleted first, its global links dangle: `npm rm -g` cannot
+// read the package any more and leaves bin/logwork behind, which then blocks
+// `npm install -g logwork-cli` and `npm link` with EEXIST. Remove only links
+// that point into a logwork-helper path that no longer exists.
+export async function removeDanglingLegacyLinks(globalPrefix, {
+  platform = process.platform,
+  lstatFn = fs.lstat,
+  statFn = fs.stat,
+  readlinkFn = fs.readlink,
+  unlinkFn = fs.unlink
+} = {}) {
+  const removed = [];
+  if (!globalPrefix || platform === 'win32') {
+    return removed;
+  }
+  for (const relativePath of LEGACY_GLOBAL_LINKS) {
+    const path = join(globalPrefix, relativePath);
+    try {
+      if (!(await lstatFn(path)).isSymbolicLink()) {
+        continue;
+      }
+      if (!/logwork-helper/.test(await readlinkFn(path))) {
+        continue;
+      }
+      try {
+        await statFn(path);
+        continue;
+      } catch {
+        // Dangling: the target is gone.
+      }
+      await unlinkFn(path);
+      removed.push(path);
+    } catch {
+      // Missing or unreadable: nothing to clean.
+    }
+  }
+  return removed;
+}
+
+function readNpmGlobalPrefix(cwd) {
+  return new Promise((resolveValue) => {
+    const invocation = npmInvocation(['prefix', '-g']);
+    const child = spawn(invocation.command, invocation.args, { cwd, shell: invocation.shell, stdio: ['ignore', 'pipe', 'ignore'] });
+    let stdout = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.on('error', () => resolveValue(''));
+    child.on('close', (code) => resolveValue(code === 0 ? stdout.trim() : ''));
+  });
+}
+
 export async function linkGlobalBinaries(targetDir, {
   runner = runCommand,
-  commandFinder = findCommandOnPath
+  commandFinder = findCommandOnPath,
+  prefixReader = readNpmGlobalPrefix,
+  legacyLinkCleaner = removeDanglingLegacyLinks
 } = {}) {
   // Best effort: drop the pre-rename global package so its `logwork` bin does
   // not block linking this one. A no-op when it is not installed.
@@ -253,6 +353,10 @@ export async function linkGlobalBinaries(targetDir, {
     cwd: targetDir,
     stdio: 'ignore'
   }).catch(() => {});
+  await Promise.resolve()
+    .then(() => prefixReader(targetDir))
+    .then((prefix) => legacyLinkCleaner(prefix))
+    .catch(() => []);
 
   try {
     await runner('npm', ['link'], {
@@ -435,6 +539,10 @@ export function formatSetupUserInstructions({
     'GitHub Copilot / VS Code mcp.json:',
     JSON.stringify(vscodeMcpConfig(entryPath), null, 2),
     '',
+    'AI agent skill (log work from your commits)',
+    '- Claude Code / Codex: run `logwork skill install`.',
+    '- Other MCP clients: use the MCP prompt "log_from_commits".',
+    '',
     'Verify',
     '- Restart or reload your IDE MCP tools after pasting config.',
     '- In the IDE, ask: Check my logwork for this week.',

package/commands/skill.mjs

@@ -0,0 +1,91 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { SKILL_NAME, readLogworkSkill } from '../lib/agent-skill.mjs';
+
+// `logwork skill`            print the agent skill (SKILL.md)
+// `logwork skill install`    copy it to ~/.claude/skills and ~/.codex/skills
+export const SKILL_TARGETS = Object.freeze({
+  claude: (home) => join(home, '.claude', 'skills', SKILL_NAME, 'SKILL.md'),
+  codex: (home) => join(home, '.codex', 'skills', SKILL_NAME, 'SKILL.md')
+});
+
+export function parseSkillArgs(args = []) {
+  const options = { action: 'print', targets: [], dir: undefined, help: false };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--target' || arg === '--dir') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`${arg} requires a value.`);
+      }
+      if (arg === '--dir') {
+        options.dir = value;
+      } else {
+        options.targets.push(...value.split(','));
+      }
+      index += 1;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown skill option: ${arg}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (positional.length > 1 || (positional[0] && !['print', 'install'].includes(positional[0]))) {
+    throw new Error('Usage: logwork skill [print|install] [--target claude|codex|all] [--dir <path>]');
+  }
+  options.action = positional[0] || 'print';
+  const targets = options.targets.length ? options.targets : ['all'];
+  options.targets = targets.includes('all') ? Object.keys(SKILL_TARGETS) : targets;
+  for (const target of options.targets) {
+    if (!SKILL_TARGETS[target]) {
+      throw new Error(`Unknown skill target: ${target}. Use claude, codex or all.`);
+    }
+  }
+  return options;
+}
+
+export async function run(args = [], {
+  home = homedir(),
+  print = console.log,
+  mkdirFn = mkdir,
+  writeFileFn = writeFile
+} = {}) {
+  const options = parseSkillArgs(args);
+  if (options.help) {
+    print(formatSkillHelp());
+    return 0;
+  }
+  const content = `${readLogworkSkill({ withFrontmatter: true }).trim()}\n`;
+  if (options.action === 'print') {
+    print(content);
+    return 0;
+  }
+  const paths = options.dir
+    ? [join(resolve(options.dir), SKILL_NAME, 'SKILL.md')]
+    : options.targets.map((target) => SKILL_TARGETS[target](home));
+  for (const path of paths) {
+    await mkdirFn(join(path, '..'), { recursive: true });
+    await writeFileFn(path, content, 'utf8');
+    print(`Installed the logwork skill: ${path}`);
+  }
+  print('Restart the agent so it picks up the skill. The same procedure is served as the MCP prompt "log_from_commits".');
+  return 0;
+}
+
+export function formatSkillHelp() {
+  return `Usage:
+  logwork skill                        Print the agent skill (SKILL.md)
+  logwork skill install                Install it for Claude Code and Codex
+  logwork skill install --target claude|codex|all
+  logwork skill install --dir <path>   Install under <path>/logwork/SKILL.md
+                                       (for example a repo's .claude/skills)
+
+The skill tells an AI agent how to log accurate work from your git commits:
+get_logwork -> draft_from_commits -> list_tasks -> review with you -> log_work.
+Other agents (Cursor, Copilot) can use the MCP prompt "log_from_commits", or
+paste \`logwork skill\` output into their rules.`;
+}

package/docs/mcp-setup.md

@@ -73,7 +73,7 @@ If you used `logwork-helper` before, delete its old MCP entry. It points at `~/.
 
 ## Exposed Tools
 
-After editing the config, restart or reload the IDE. The server exposes 15 tools. Each one has a title, a description, a described input schema, and MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so IDEs and agents can tell read-only tools from writes.
+After editing the config, restart or reload the IDE. The server exposes 16 tools and one prompt. Each one has a title, a description, a described input schema, and MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so IDEs and agents can tell read-only tools from writes.
 
 The server also sends MCP `instructions` that explain the approval rules, the line format and the recommended call order. Most clients pass these to the model automatically.
 
@@ -89,6 +89,7 @@ Previews expire after 1 hour. They are also lost when the server restarts.
 | Group | Tool | Kind | Purpose |
 |---|---|---|---|
 | Read | `get_logwork` | read-only | Booked vs logged RO hours by day and project, with entries (`logworkId`, worklog task, description, status). |
+| Read | `draft_from_commits` | read-only | Your git commits (all branches, your author) for a period in the given `repos`, grouped per day into draft lines with a suggested worklog task and hours that fill the RO remaining booked time. Returns `draftText` for `log_work`. |
 | Read | `list_projects` | read-only | RO memberships (`projectMemberId`, `projectId`, `projectName`) and local mappings. |
 | Read | `list_tasks` | read-only | RO worklog task catalog for one `projectId`: id, name, type of work, and when to use each task. |
 | Read | `get_jira_issue` | read-only | Jira issue key, summary and status. |
@@ -106,7 +107,7 @@ Previews expire after 1 hour. They are also lost when the server restarts.
 
 ### Tool Name Changes From logwork-helper
 
-| logwork-helper (before 0.3.0) | logwork-cli |
+| logwork-helper (0.2.x and earlier) | logwork-cli |
 |---|---|
 | `preview_logwork_batch`, `apply_logwork_batch` | `log_work` |
 | `query_logwork` | `get_logwork` |
@@ -172,8 +173,28 @@ Log 2 hours today for SCB-213 "maintenance mode UI" as Feature Development, with
 Set up the SCB ticket mapping to project 2621A-SIT-HTML BUILDER-PRJ.
 ```
 
+**Prompt `log_from_commits`** (arguments: `period`, `repos`) returns the full procedure for logging from commits. It is the same text as the agent skill that `logwork skill install` installs for Claude Code and Codex.
+
 ## Common MCP Workflows
 
+### Log Work From Your Commits
+
+Ask your assistant (or pick the `log_from_commits` prompt in clients that list MCP prompts):
+
+```text
+Log my work for yesterday from my commits in this workspace.
+```
+
+Expected flow:
+
+1. `get_logwork` shows which days and projects still have booked hours to fill.
+2. `draft_from_commits` (with `repos` set to the workspace folders) groups your commits into draft lines with hours.
+3. `list_tasks` confirms the worklog task names for each project.
+4. The assistant rewrites vague descriptions, shows you the block and waits for approval.
+5. `log_work(text)` previews the entries, then `log_work(batchId, confirm: true)` applies them.
+
+
+
 ### Query Logwork
 
 Ask your assistant:

package/docs/operations-guide.md

@@ -19,6 +19,8 @@ npm install -g logwork-cli
 logwork setup
 ```
 
+Upgrading from `logwork-helper`: run `npm uninstall -g logwork-helper` first. Both packages provide a `logwork` command, and npm refuses to overwrite it (`EEXIST`). If `~/.logwork-helper` was already deleted, the uninstall leaves broken links behind; remove them with `P="$(npm prefix -g)"; rm -f "$P/bin/logwork" "$P"/bin/logwork-helper* "$P/lib/node_modules/logwork-helper"`, or run `npx logwork-cli@latest setup`, which removes them.
+
 Authenticate each target from Terminal:
 
 ```bash

package/lib/agent-skill.mjs

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// skills/logwork/SKILL.md is the single source for the agent procedure: it is
+// shipped as an installable skill (`logwork skill install`) and served as the
+// MCP prompt log_from_commits.
+export const SKILL_NAME = 'logwork';
+export const SKILL_PATH = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skills', SKILL_NAME, 'SKILL.md');
+
+export function readLogworkSkill({ withFrontmatter = false, path = SKILL_PATH } = {}) {
+  // Normalise CRLF (Windows git checkouts) so the frontmatter strip and the
+  // installed copies are identical on every platform.
+  const text = readFileSync(path, 'utf8').replace(/\r\n/g, '\n');
+  return withFrontmatter ? text : text.replace(/^---\n[\s\S]*?\n---\n+/, '').trim();
+}

package/lib/batch-parser.mjs

@@ -1,6 +1,8 @@
 const DAY_HEADING_RE = /^(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday),\s+(\d{2})\s+([A-Za-z]{3})\s+(\d{4})$/;
 const ENTRY_RE = /^\+(\d+(?:\.\d+)?)\s+(.+)$/;
 const TICKET_RE = /\b[A-Z][A-Z0-9]+-\d+\b/g;
+const MAX_DAY_HOURS = 24;
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
 
 const MONTHS = new Map([
   ['jan', 1],
@@ -67,6 +69,18 @@ export function parseWeeklyLogText(text) {
       });
       continue;
     }
+    // RO rejects more than 24h; catching it here keeps a batch from failing
+    // halfway after earlier entries were written.
+    const dayTotal = entries.filter((item) => item.date === currentDate).reduce((sum, item) => sum + item.hours, 0) + hours;
+    if (hours > MAX_DAY_HOURS || dayTotal > MAX_DAY_HOURS) {
+      errors.push({
+        line: lineNumber,
+        message: hours > MAX_DAY_HOURS
+          ? `Hours ${entry[1]} exceed ${MAX_DAY_HOURS}h for one entry.`
+          : `Entries for ${currentDate} add up to ${dayTotal}h, more than ${MAX_DAY_HOURS}h in one day.`
+      });
+      continue;
+    }
 
     const text = entry[2].trim();
     const { taskName, description, taskExplicit } = splitTaskAndDescription(text);
@@ -137,6 +151,15 @@ function parseHeadingDate(match, lineNumber, errors) {
     return null;
   }
 
+  const weekday = WEEKDAYS[date.getUTCDay()];
+  if (weekday !== match[1]) {
+    errors.push({
+      line: lineNumber,
+      message: `Date heading says ${match[1]} but ${match[2]} ${match[3]} ${match[4]} is a ${weekday}: ${match[0]}`
+    });
+    return null;
+  }
+
   return [
     String(year).padStart(4, '0'),
     String(month).padStart(2, '0'),

package/lib/batch-workflow.mjs

@@ -70,7 +70,11 @@ export async function previewLogworkBatch({
       defaultWorklogTask: normalizedDefaultTask
     }
     : enriched;
-  return typeOfWork ? { ...output, typeOfWork } : output;
+  // typeOfWork also changes what gets written, so it is folded into the
+  // batchId the same way.
+  return typeOfWork
+    ? { ...output, typeOfWork, batchId: `${output.batchId}_${hash(`typeOfWork:${typeOfWork}`)}`, summary: `${output.summary}\n\nType of work for every entry: ${typeOfWork}` }
+    : output;
 }
 
 export const LOGWORK_LINE_FORMAT = '+<hours> <worklog task> | <description>';
@@ -394,6 +398,16 @@ export async function applyLogworkBatch({
         ok: false,
         error: error.message
       });
+      // Earlier entries are already in RO. Say so plainly: re-applying the same
+      // text would log them twice.
+      const written = results.filter((result) => result.ok);
+      const notTried = preview.entries.slice(results.length).map((item) => item.id);
+      error.message = `Entry ${entry.id} (+${entry.hours}h ${entry.taskName}) failed: ${error.message}` +
+        (written.length
+          ? ` Already written to RO: ${written.map((result) => `${result.entryId} (+${result.hours}h ${result.taskName})`).join(', ')}. Do not apply this batch again; preview only the entries that were not written.`
+          : ' Nothing was written.') +
+        (notTried.length ? ` Not attempted: ${notTried.join(', ')}.` : '');
+      error.partialResults = results;
       error.applyLedger = await recordRoApplyLedger({
         writer: ledgerWriter,
         preview,