handoff-mcp-server 0.11.0 → 0.13.0

package/Cargo.lock

@@ -144,10 +144,11 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.11.0"
+version = "0.13.0"
 dependencies = [
  "anyhow",
  "chrono",
+ "lexsim",
  "serde",
  "serde_json",
  "tempfile",
@@ -242,6 +243,16 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
+[[package]]
+name = "lexsim"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "579b9d7ab407540bead4688eaf1675410a198d77c237a30cda55597df98926e1"
+dependencies = [
+ "unicode-normalization",
+ "unicode-segmentation",
+]
+
 [[package]]
 name = "libc"
 version = "0.2.186"
@@ -454,6 +465,21 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "tinyvec"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e61e67053d25a4e82c844e8424039d9745781b3fc4f32b8d55ed50f5f667ef3"
+dependencies = [
+ "tinyvec_macros",
+]
+
+[[package]]
+name = "tinyvec_macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+
 [[package]]
 name = "toml"
 version = "0.8.23"
@@ -501,6 +527,21 @@ version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
+[[package]]
+name = "unicode-normalization"
+version = "0.1.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5fd4f6878c9cb28d874b009da9e8d183b5abc80117c40bbd187a1fde336be6e8"
+dependencies = [
+ "tinyvec",
+]
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
 [[package]]
 name = "unicode-xid"
 version = "0.2.6"

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.11.0"
+version = "0.13.0"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"
@@ -9,7 +9,7 @@ homepage = "https://github.com/alphaelements/handoff-mcp"
 readme = "README.md"
 keywords = ["mcp", "ai", "claude", "handoff", "context"]
 categories = ["command-line-utilities", "development-tools"]
-rust-version = "1.70"
+rust-version = "1.85"
 exclude = ["lefthook.yml", "tmp/", "wiki/", "docs/", ".claude/", ".vscode/"]
 
 [dependencies]
@@ -20,6 +20,7 @@ toml_edit = "0.22"
 chrono = { version = "0.4", features = ["serde"] }
 anyhow = "1"
 thiserror = "2"
+lexsim = "0.1.0"
 
 [dev-dependencies]
 tempfile = "3.27.0"

package/README.md

@@ -155,9 +155,21 @@ rename) so a concurrent reader never sees a partially-written file.
 | `handoff_dashboard` | Overview of all handoff-enabled projects |
 | `handoff_import_context` | Bulk import tasks and session data from documents |
 | `handoff_refer` | Send a cross-project referral (bug, improvement, request) |
-| `handoff_list_referrals` | List incoming referrals from other projects |
+| `handoff_list_referrals` | List incoming referrals from other projects (summaries only) |
+| `handoff_get_referral` | Fetch one incoming referral in full — details, suggested tasks, done_criteria, context |
 | `handoff_update_referral` | Update referral status (open → acknowledged → resolved) |
 
+### Project Memory
+
+| Tool | Purpose |
+|------|---------|
+| `memory_save` | Save a durable project memory (lesson/rule/convention/gotcha); detects exact and near-duplicate memories and hands near-duplicates back for AI-driven merge |
+| `memory_query` | Return the memories most relevant to the current prompt/file (BM25 + scope-path boost); with a `session_id`, suppresses repeats already injected this session |
+| `memory_delete` | Delete a memory by id (full id or unique prefix) |
+| `memory_cleanup` | Housekeeping (for SessionStart): silently merge exact duplicates, return near-duplicate/stale recommendations, gc old injection sidecars |
+
+See [Project Memory](#project-memory-1) below for what it is and how to wire automatic injection.
+
 ### Task Data Model
 
 Tasks are stored as a directory tree with status encoded in filenames:
@@ -223,9 +235,11 @@ name = "my-project"
 description = "Project description"
 
 [settings]
-history_limit = 20         # Max closed sessions to keep
-done_task_limit = 10       # Max completed tasks to show
-auto_git_summary = true    # Capture git state automatically
+history_limit = 20            # Max closed sessions to keep
+done_task_limit = 10          # Max completed tasks to show
+auto_git_summary = true       # Capture git state automatically
+require_estimate_hours = true # Require estimate_hours on leaf tasks (default true)
+ai_estimate_multiplier = 0.2  # Multiplier turning human estimates into AI-effort hours
 
 [dashboard]
 scan_dirs = ["~/pro/"]     # Directories to scan for dashboard
@@ -263,6 +277,147 @@ mode = "compare"           # plan, actual, compare
 
 All configuration sections can be updated via `handoff_update_config` with dot-notation keys (e.g., `"calendar.work_hours_per_day": 7`).
 
+### Estimates and AI effort
+
+handoff-mcp distinguishes the **raw human-effort estimate** you record on a task
+from the **AI-effort hours** used in scheduling and metrics:
+
+- **`require_estimate_hours`** (default `true`) — `handoff_update_task` rejects
+  creating or updating a *leaf* task (in `todo` / `in_progress` / `review` /
+  `done`) without `schedule.estimate_hours > 0`. Parent tasks (with children) and
+  `blocked` / `skipped` tasks are exempt, and an estimate already on the task
+  satisfies the requirement. Set to `false` to opt out.
+- **`ai_estimate_multiplier`** (default `0.2`) — the factor applied to raw
+  estimates to model how long the work takes when an AI agent does it. Always
+  record the *raw human-effort* estimate; the multiplier is applied at
+  aggregation time by `handoff_get_metrics` (`total_adjusted_estimate_hours` and
+  per-milestone `adjusted_estimate_hours`) and `handoff_get_capacity`. Raw values
+  are never overwritten.
+
+## Project Memory
+
+Sessions answer *"what was I doing last time?"*. **Memory** answers a longer-lived
+question: *"what should every session in this project always know?"* — durable
+lessons, rules, conventions, and gotchas that outlive any one session.
+
+Memories live in `.handoff/memory/` (one JSON file per memory, plus per-session
+`injected/` sidecars). A built-in multilingual similarity engine (Japanese /
+English, dictionary-free) ranks relevance and detects duplicates, all in-memory
+and sub-millisecond.
+
+### Using it directly
+
+The agent can call the memory tools at any time:
+
+- `memory_save` — record a memory. An exact duplicate is reported (not
+  rewritten); a near-duplicate comes back as a `conflict` with both bodies so the
+  agent can merge them (`merge_into=<id>`, `absorb_ids=[…]`) or save separately
+  with `force=true`. **handoff-mcp never merges for you** — it surfaces both
+  bodies and lets the agent decide.
+- `memory_query` — fetch the memories most relevant to some text and/or files.
+- `memory_delete` / `memory_cleanup` — prune and de-duplicate the store.
+
+### Automatic injection via hooks
+
+MCP is request/response — the server cannot push a memory into the agent's
+context on its own. **Claude Code hooks** close that gap: they fire regardless of
+what the agent intends, call `memory_query`, and inject the matching memories as
+`additionalContext`. A per-session diff (keyed on the hook `session_id`) ensures
+the same memory is **not injected twice in one session** — and an *edited* memory
+(new content hash) is re-injected.
+
+| Event | Calls | Effect |
+|-------|-------|--------|
+| `UserPromptSubmit` | `memory_query` (prompt text) | Inject memories relevant to the prompt |
+| `PreToolUse` (`Edit\|Write\|MultiEdit`) | `memory_query` (file path) | Inject memories scoped to the file being edited |
+| `SessionStart` | `memory_cleanup` | Merge exact duplicates, gc old sidecars |
+
+> **Wire hooks in your *user/global* settings, not in the repo.** Hooks are a
+> personal workflow choice; the handoff-mcp repo does not ship a `.claude/`
+> hooks config, and you should not commit one into a shared project. Put the
+> config in `~/.claude/settings.json` (global) or your own
+> `.claude/settings.local.json` (git-ignored).
+
+**Native `mcp_tool` hook (preferred).** Recent Claude Code versions can call an
+MCP tool from a hook directly, with no wrapper script. In
+`~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [ {
+        "type": "mcp_tool", "server": "handoff", "tool": "memory_query",
+        "input": { "project_dir": "${cwd}",
+                   "session_id": "${session_id}", "text": "${prompt}" }
+      } ] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write|MultiEdit", "hooks": [ {
+        "type": "mcp_tool", "server": "handoff", "tool": "memory_query",
+        "input": { "project_dir": "${cwd}",
+                   "session_id": "${session_id}", "tool_name": "${tool_name}",
+                   "text": "${tool_input.file_path}",
+                   "file_paths": ["${tool_input.file_path}"] }
+      } ] }
+    ],
+    "SessionStart": [
+      { "hooks": [ {
+        "type": "mcp_tool", "server": "handoff", "tool": "memory_cleanup",
+        "input": { "project_dir": "${cwd}" }
+      } ] }
+    ]
+  }
+}
+```
+
+(`server` must match the name you registered handoff-mcp under — `handoff` in the
+[Setup](#setup) examples.)
+
+**Wrapper script fallback.** If your Claude Code version doesn't support the
+`mcp_tool` hook type, use the bundled `command` wrapper
+[`scripts/handoff-memory-hook.py`](scripts/handoff-memory-hook.py). It reads the
+hook JSON on stdin, calls the server over JSON-RPC, and emits
+`additionalContext` — the memory tools return their payload as a JSON *string* so
+both paths parse it identically. Point all three hooks at it:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [ { "type": "command",
+        "command": "/path/to/handoff-mcp/scripts/handoff-memory-hook.py" } ] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write|MultiEdit", "hooks": [ { "type": "command",
+        "command": "/path/to/handoff-mcp/scripts/handoff-memory-hook.py" } ] }
+    ],
+    "SessionStart": [
+      { "hooks": [ { "type": "command",
+        "command": "/path/to/handoff-mcp/scripts/handoff-memory-hook.py" } ] }
+    ]
+  }
+}
+```
+
+The script resolves the `handoff-mcp` binary from `PATH` (override with
+`HANDOFF_MCP_BIN`) and **fails safe**: on any error it prints nothing and exits
+0, so a memory miss is silent and never blocks your prompt.
+
+### Memory settings
+
+All under `[settings]` in `.handoff/config.toml`, all with safe defaults
+(existing projects need no change), all settable via `handoff_update_config`:
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `memory_enabled` | `true` | Master switch. When `false`, all four memory tools return a benign empty result and write nothing |
+| `memory_dup_threshold` | `0.72` | Jaccard similarity at/above which a save is a near-duplicate conflict and cleanup groups a cluster |
+| `memory_query_min_score` | `0.5` | BM25 relevance floor for `memory_query` results |
+| `memory_query_limit` | `5` | Max memories returned per query |
+| `memory_stale_days` | `60` | Days without a reference before a memory is flagged stale |
+| `memory_injected_gc_days` | `14` | Age at which per-session injection sidecars are garbage-collected |
+
 ## MCP Resources
 
 | URI | Description |
@@ -290,6 +445,10 @@ This project uses handoff-mcp for session continuity.
 - **Decisions**: Record decisions with confidence levels as they are made,
   not just at session end. Use `confirmed` for verified facts, `estimated`
   for reasonable assumptions, `unverified` for unknowns.
+- **Project memory**: Use `memory_save` to record durable lessons, rules,
+  conventions, and gotchas that every future session should know. Use
+  `memory_query` to retrieve relevant memories. Near-duplicate memories are
+  surfaced as conflicts for you to merge or force-save — never merged silently.
 ```
 
 ## Skill File (Optional)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",

package/scripts/cargo-env.sh

@@ -0,0 +1,29 @@
+# shellcheck shell=sh
+# cargo-env.sh — make cargo commands work across heterogeneous dev environments.
+#
+# Some environments (e.g. a Docker image where CARGO_HOME=/usr/local/cargo is
+# owned by root) expose a CARGO_HOME that the current user cannot write to.
+# cargo then fails to download/cache crates or fetch the advisory-db, breaking
+# the git hooks even though nothing is wrong with the code.
+#
+# This script detects an unwritable CARGO_HOME and transparently falls back to
+# the per-user $HOME/.cargo, which every supported environment can write to.
+# When CARGO_HOME is already writable (local macOS, a synced Mac, or simply
+# unset so cargo uses its default ~/.cargo) it leaves the environment untouched.
+#
+# Usage (from a hook or shell):
+#   . scripts/cargo-env.sh && cargo <args>
+
+# Resolve the directory cargo would use right now.
+_cargo_home="${CARGO_HOME:-$HOME/.cargo}"
+
+# Probe writability with a temp file; fall back to $HOME/.cargo if we can't write.
+if ! ( mkdir -p "$_cargo_home" 2>/dev/null && touch "$_cargo_home/.cargo-env-wtest" 2>/dev/null ); then
+  export CARGO_HOME="$HOME/.cargo"
+  mkdir -p "$CARGO_HOME" 2>/dev/null || true
+else
+  rm -f "$_cargo_home/.cargo-env-wtest" 2>/dev/null || true
+  export CARGO_HOME="$_cargo_home"
+fi
+
+unset _cargo_home

package/scripts/handoff-memory-hook.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Claude Code hook wrapper for handoff-mcp project memory.
+
+This is the **fallback path** for memory auto-injection. The preferred wiring is
+a native ``mcp_tool`` hook that calls ``memory_query`` / ``memory_cleanup``
+directly (see README "Project Memory"); this script exists for Claude Code
+versions that lack the ``mcp_tool`` hook type, by translating a Claude Code hook
+event into a single JSON-RPC ``tools/call`` against the handoff-mcp server and
+emitting the result as ``hookSpecificOutput.additionalContext``.
+
+It speaks the server's line-delimited JSON-RPC over stdio: one request object on
+one line in, one response object on one line out. ``memory_query`` /
+``memory_cleanup`` return their payload as a JSON *string* inside
+``result.content[0].text`` (so both this wrapper and the native hook path parse
+it identically), which this script re-parses.
+
+Wiring (in ``~/.claude/settings.json`` — do NOT commit this into a repo):
+
+    {
+      "hooks": {
+        "UserPromptSubmit": [
+          { "hooks": [ { "type": "command",
+              "command": "handoff-mcp-memory-hook" } ] }
+        ],
+        "PreToolUse": [
+          { "matcher": "Edit|Write|MultiEdit",
+            "hooks": [ { "type": "command",
+              "command": "handoff-mcp-memory-hook" } ] }
+        ],
+        "SessionStart": [
+          { "hooks": [ { "type": "command",
+              "command": "handoff-mcp-memory-hook" } ] }
+        ]
+      }
+    }
+
+The same script handles all three events; it picks the tool from
+``hook_event_name`` on stdin.
+
+Environment:
+- ``HANDOFF_MCP_BIN`` — path to the ``handoff-mcp`` binary (default: ``handoff-mcp``
+  resolved on ``PATH``).
+
+Design contract: this script must **never break the session**. On any error
+(binary missing, bad JSON, timeout) it prints nothing and exits 0 — a memory
+miss is silent, never a blocked prompt.
+"""
+
+# `X | None` annotations are evaluated lazily so this runs on Python 3.7+
+# (a hook host may not have 3.10). The annotations are never evaluated at runtime.
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+# Map a Claude Code hook event to the memory tool it drives.
+QUERY_EVENTS = {"UserPromptSubmit", "PreToolUse"}
+CLEANUP_EVENTS = {"SessionStart"}
+
+# How long to wait for the server to answer one request, in seconds. The query
+# is in-memory and sub-millisecond; this is just a safety net so a hung binary
+# can never stall the prompt.
+TIMEOUT_SECONDS = 5.0
+
+
+def _server_bin() -> str | None:
+    """Resolve the handoff-mcp binary path, or None if it can't be found."""
+    explicit = os.environ.get("HANDOFF_MCP_BIN")
+    if explicit:
+        return explicit if os.path.exists(explicit) else None
+    return shutil.which("handoff-mcp")
+
+
+def _call(bin_path: str, tool: str, arguments: dict) -> dict | None:
+    """Send one ``tools/call`` line and parse the inner JSON payload.
+
+    Returns the decoded inner object (e.g. ``{"memories": [...]}`), or None on
+    any transport / decode failure. The server is stateless per line, so no
+    ``initialize`` handshake is needed — a bare ``tools/call`` is answered.
+    """
+    request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {"name": tool, "arguments": arguments},
+    }
+    try:
+        proc = subprocess.run(
+            [bin_path],
+            input=json.dumps(request) + "\n",
+            capture_output=True,
+            text=True,
+            timeout=TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+    # The response is the first non-empty stdout line (stderr carries the
+    # startup banner and is ignored).
+    line = next((ln for ln in proc.stdout.splitlines() if ln.strip()), None)
+    if not line:
+        return None
+    try:
+        envelope = json.loads(line)
+        text = envelope["result"]["content"][0]["text"]
+        return json.loads(text)
+    except (json.JSONDecodeError, KeyError, IndexError, TypeError):
+        return None
+
+
+def _file_paths_from_tool_input(tool_input) -> list[str]:
+    """Pull file paths out of a PreToolUse ``tool_input`` (Edit/Write/MultiEdit)."""
+    if not isinstance(tool_input, dict):
+        return []
+    paths = []
+    fp = tool_input.get("file_path")
+    if isinstance(fp, str) and fp:
+        paths.append(fp)
+    # MultiEdit and similar may carry an edits array; each can name a file.
+    for edit in tool_input.get("edits", []) or []:
+        if isinstance(edit, dict):
+            efp = edit.get("file_path")
+            if isinstance(efp, str) and efp:
+                paths.append(efp)
+    return paths
+
+
+def _emit(event: str, context: str) -> None:
+    """Print a Claude Code hook output object carrying additionalContext."""
+    if not context:
+        return
+    out = {
+        "hookSpecificOutput": {
+            "hookEventName": event,
+            "additionalContext": context,
+        }
+    }
+    print(json.dumps(out))
+
+
+def _format_memories(payload: dict) -> str:
+    """Turn a ``memory_query`` payload into an injectable context block."""
+    memories = payload.get("memories") or []
+    if not memories:
+        return ""
+    lines = ["Relevant project memories (handoff-mcp):"]
+    for m in memories:
+        text = (m.get("text") or "").strip()
+        if not text:
+            continue
+        kind = m.get("kind") or "memory"
+        lines.append(f"- [{kind}] {text}")
+    # Only a header with no bullets means nothing useful to inject.
+    return "\n".join(lines) if len(lines) > 1 else ""
+
+
+def main() -> int:
+    raw = sys.stdin.read()
+    try:
+        hook = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError:
+        return 0  # malformed hook input — stay silent, never block
+
+    event = hook.get("hook_event_name") or ""
+    bin_path = _server_bin()
+    if not bin_path:
+        return 0  # server not installed — nothing to inject
+
+    project_dir = hook.get("cwd") or os.getcwd()
+    session_id = hook.get("session_id")
+
+    if event in QUERY_EVENTS:
+        # UserPromptSubmit → match the prompt. PreToolUse → match the file(s).
+        prompt = hook.get("prompt") or ""
+        tool_name = hook.get("tool_name")
+        file_paths = _file_paths_from_tool_input(hook.get("tool_input"))
+        # Text fed to BM25: the prompt for UserPromptSubmit, else the file paths
+        # (the server also adds basenames + tool_name to the query).
+        text = prompt if prompt else " ".join(file_paths)
+        arguments = {"project_dir": project_dir, "text": text}
+        if session_id:
+            arguments["session_id"] = session_id
+        if tool_name:
+            arguments["tool_name"] = tool_name
+        if file_paths:
+            arguments["file_paths"] = file_paths
+
+        payload = _call(bin_path, "memory_query", arguments)
+        if payload:
+            _emit(event, _format_memories(payload))
+        return 0
+
+    if event in CLEANUP_EVENTS:
+        # Housekeeping only: merge exact duplicates and gc sidecars. We do not
+        # inject the cleanup recommendations as context (that is for an explicit
+        # AI-driven pass), so there is no additionalContext to emit here.
+        _call(bin_path, "memory_cleanup", {"project_dir": project_dir})
+        return 0
+
+    # Unknown event — nothing to do.
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/handoff/SKILL.md

@@ -54,6 +54,13 @@ description: "Session handoff — load context at start, save at end, track task
   user that their input is needed before proceeding.
 - Create new tasks as work is discovered. Always include `done_criteria` with
   verifiable items so completion can be tracked.
+- **Always set `schedule.estimate_hours`** (raw human-effort hours, > 0) on every
+  leaf task. It is required by default — `handoff_update_task` rejects creating or
+  updating a leaf task without it (parent tasks and `blocked`/`skipped` tasks are
+  exempt). Enter the raw human-effort estimate; the AI-effort multiplier
+  (`settings.ai_estimate_multiplier`, default 0.2) is applied automatically at
+  aggregation time by `handoff_get_metrics`/`handoff_get_capacity`. To turn the
+  requirement off, set `settings.require_estimate_hours = false`.
 
 ### Progressive done_criteria Checking
 - **Check off `done_criteria` immediately as each item is verified** — do not
@@ -91,7 +98,7 @@ description: "Session handoff — load context at start, save at end, track task
 Use `handoff_log_time` to record hours worked on a task:
 - Atomically adds to `schedule.actual_hours` and deducts from `schedule.remaining_hours`.
 - Never overwrite `actual_hours` directly — always use the additive `handoff_log_time` tool.
-- Set `schedule.estimate_hours` on task creation so metrics can show estimate vs actual.
+- Set `schedule.estimate_hours` on task creation (required by default) so metrics can show estimate vs actual.
 - When the handoff-vscode time tracker is enabled, the extension also logs time
   automatically — the AI does not need to log time manually for extension-tracked tasks.
 - `handoff_update_task`'s `schedule` field **merges** (partial update): passing

package/src/mcp/handlers/capacity.rs

@@ -4,6 +4,7 @@ use serde_json::{json, Value};
 use toml_edit::DocumentMut;
 
 use super::resolve_project_dir;
+use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::tasks::{build_task_index, is_terminal_status, TaskIndex};
 
@@ -54,9 +55,12 @@ pub fn handle(arguments: &Value) -> Result<String> {
     }
 
     // Calculate allocated hours from tasks
+    let multiplier = read_config(&config_path)
+        .map(|c| c.settings.ai_estimate_multiplier)
+        .unwrap_or(0.2);
     if tasks_dir.exists() {
         let (tree, _) = build_task_index(&tasks_dir, u32::MAX)?;
-        allocate_task_hours(&tree, assignee_filter, &start, &end, &mut days);
+        allocate_task_hours(&tree, assignee_filter, &start, &end, &mut days, multiplier);
     }
 
     let allocated_hours: f64 = days
@@ -260,6 +264,7 @@ fn allocate_task_hours(
     start: &NaiveDate,
     end: &NaiveDate,
     days: &mut [Value],
+    multiplier: f64,
 ) {
     for node in tree {
         if is_terminal_status(&node.status) {
@@ -278,10 +283,13 @@ fn allocate_task_hours(
                         NaiveDate::parse_from_str(sd, "%Y-%m-%d"),
                         NaiveDate::parse_from_str(dd, "%Y-%m-%d"),
                     ) {
-                        let est = sched
-                            .remaining_hours
-                            .or(sched.estimate_hours)
-                            .unwrap_or(0.0);
+                        // remaining_hours is already actual AI-effort progress, so it
+                        // is used as-is; the raw estimate is human-effort and gets the
+                        // AI multiplier applied to derive AI-effort allocation.
+                        let est = match sched.remaining_hours {
+                            Some(rem) => rem,
+                            None => sched.estimate_hours.unwrap_or(0.0) * multiplier,
+                        };
                         let overlap_start = (*start).max(task_start);
                         let overlap_end = (*end).min(task_end);
                         if overlap_start <= overlap_end {
@@ -311,6 +319,13 @@ fn allocate_task_hours(
             }
         }
 
-        allocate_task_hours(&node.children, assignee_filter, start, end, days);
+        allocate_task_hours(
+            &node.children,
+            assignee_filter,
+            start,
+            end,
+            days,
+            multiplier,
+        );
     }
 }