feat: pack honesty score + artifact drift + gap-fill (0.28.0) (#56)

Port 3 mechanisms from mex (github.com/theDakshJaitly/mex) into the
deterministic, zero-LLM completeness layer:

- Artifact drift checkers: MissingFile / DeadCommit / BrokenLink over a
  task's aggregated Artifacts. Pure check_artifacts core + git/FS wrapper
  assess_artifacts, gated on is_git_repo so there is no false drift outside
  the project repo. Wired into the pack.
- Honesty score 0-100: GapKind::weight() (error -10, warn -3, info -1) +
  CompletenessReport::score(); rendered as "honesty score: N/100".
- Gap-fill: build_gap_fill_prompt() emits a targeted prompt embedding the
  pack (like `mex sync --dry-run`); no LLM call in the binary.

Surfaces: `task-journal check <id> [--json]`, `task-journal gaps <id>
[--fill]`, and the `task_check` MCP tool.

Minor bump -> inter-crate version pins (tj-core in tj-cli/tj-mcp) bumped
to 0.28.0 so the CI registry-resolve passes.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Shahinyanm

CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.0] - 2026-06-18
+
+### Added
+- **Pack honesty score + artifact drift detection** (inspired by
+  [mex](https://github.com/theDakshJaitly/mex)). Deterministic, zero-LLM
+  checks that a task's recorded artifacts still match reality:
+  - New `GapKind`s in `completeness`: `MissingFile` (a referenced file is gone
+    from disk), `DeadCommit` (a referenced commit hash is unknown to git),
+    `BrokenLink` (a local-file link is missing). A pure
+    `check_artifacts(arts, file_exists, commit_alive)` core plus a git/FS
+    wrapper `assess_artifacts`; wired into the pack via `artifact_gaps_for_cwd`
+    (silent outside the project's git repo, so no false drift).
+  - **Honesty score 0–100** — `CompletenessReport::score()` deducts each gap's
+    weight (error −10, warn −3, info −1). Rendered in the pack's Completeness
+    section as `honesty score: N/100`.
+- **`task-journal check <id> [--json]`** — print a task's honesty score and
+  gaps (like `mex check`).
+- **`task-journal gaps <id> [--fill]`** — list gaps, or with `--fill` emit a
+  targeted, deterministic gap-fill prompt embedding the current pack (like
+  `mex sync --dry-run`) for the in-session agent to close — no LLM call in the
+  binary.
+- **`task_check` MCP tool** — returns `{score, gaps:[{kind, severity, detail}]}`
+  so an in-session agent can self-assess a task before closing.
+
 ## [0.27.0] - 2026-06-17
 
 ### Added

Cargo.lock

@@ -7,7 +7,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.27.0"
+version = "0.28.0"
 edition = "2021"
 rust-version = "1.88"
 license = "MIT"

Cargo.toml

@@ -23,7 +23,7 @@ default = ["embed"]
 embed = ["tj-core/embed"]
 
 [dependencies]
-tj-core = { package = "task-journal-core", version = "0.27.0", path = "../tj-core", default-features = false }
+tj-core = { package = "task-journal-core", version = "0.28.0", path = "../tj-core", default-features = false }
 anyhow = { workspace = true }
 clap = { workspace = true }
 tracing = { workspace = true }

crates/tj-cli/Cargo.toml

@@ -1053,6 +1053,21 @@ enum Commands {
     /// Why-this-approach, Verification, Affected). Reuses event log +
     /// artifacts; introduces no new tables.
     ExportPr { task_id: String },
+    /// Print a task's honesty score (0–100) and completeness gaps —
+    /// deterministic, zero-LLM (like `mex check`). `--json` for machines.
+    Check {
+        task_id: String,
+        #[arg(long)]
+        json: bool,
+    },
+    /// Print a targeted gap-fill prompt for a task (deterministic, zero-LLM,
+    /// like `mex sync --dry-run`); the in-session agent runs it to close gaps.
+    Gaps {
+        task_id: String,
+        /// Emit the full fix prompt (default: just list gaps + score).
+        #[arg(long)]
+        fill: bool,
+    },
     /// Export task knowledge as Claude-memory frontmatter files (feeds native dream).
     ExportMemory {
         /// Export a single task by id.
@@ -3351,6 +3366,12 @@ runs in the background and won't block you; it only fills gaps and never closes
         Commands::ExportPr { task_id } => {
             run_export_pr(&task_id)?;
         }
+        Commands::Check { task_id, json } => {
+            run_check(&task_id, json)?;
+        }
+        Commands::Gaps { task_id, fill } => {
+            run_gaps(&task_id, fill)?;
+        }
         Commands::ExportMemory {
             task,
             all_closed,
@@ -3766,6 +3787,109 @@ fn run_export_pr(task_id: &str) -> Result<()> {
     Ok(())
 }
 
+/// Severity label for a gap weight (10/3/1 → error/warn/info).
+fn severity_for(weight: u32) -> &'static str {
+    match weight {
+        10 => "error",
+        3 => "warn",
+        _ => "info",
+    }
+}
+
+/// Open the project DB, ingest new events, and build the full completeness
+/// report — structural gaps plus artifact honesty drift — for `task_id`.
+/// Exits(1) when the task is unknown.
+fn assess_task(
+    task_id: &str,
+) -> Result<(
+    rusqlite::Connection,
+    tj_core::completeness::CompletenessReport,
+)> {
+    let cwd = std::env::current_dir()?;
+    let project_hash = tj_core::project_hash::from_path(&cwd)?;
+    let events_path = tj_core::paths::events_dir()?.join(format!("{project_hash}.jsonl"));
+    let state_path = tj_core::paths::state_dir()?.join(format!("{project_hash}.sqlite"));
+    let conn = tj_core::db::open(&state_path)?;
+    if events_path.exists() {
+        tj_core::db::ingest_new_events(&conn, &events_path, &project_hash)?;
+    }
+
+    // Typed not-found exit, mirroring run_export_pr.
+    if let Err(rusqlite::Error::QueryReturnedNoRows) = conn.query_row(
+        "SELECT 1 FROM tasks WHERE task_id = ?1",
+        rusqlite::params![task_id],
+        |r| r.get::<_, i64>(0),
+    ) {
+        eprintln!("Error: task not found: {task_id}");
+        std::process::exit(1);
+    }
+
+    let mut report =
+        tj_core::completeness::assess(&conn, task_id, tj_core::completeness::pending_count())?;
+    let arts = tj_core::db::task_artifacts(&conn, task_id)?;
+    report
+        .gaps
+        .extend(tj_core::completeness::artifact_gaps_for_cwd(&arts));
+    Ok((conn, report))
+}
+
+/// `task-journal check <id> [--json]` — print honesty score + gaps.
+fn run_check(task_id: &str, json: bool) -> Result<()> {
+    let (_conn, report) = assess_task(task_id)?;
+    if json {
+        let gaps: Vec<_> = report
+            .gaps
+            .iter()
+            .map(|g| {
+                serde_json::json!({
+                    "kind": format!("{:?}", g.kind),
+                    "severity": severity_for(g.kind.weight()),
+                    "detail": g.detail,
+                })
+            })
+            .collect();
+        let out = serde_json::json!({
+            "task_id": task_id,
+            "score": report.score(),
+            "gaps": gaps,
+        });
+        println!("{}", serde_json::to_string_pretty(&out)?);
+    } else {
+        println!(
+            "honesty score: {}/100 ({} gap(s))",
+            report.score(),
+            report.gaps.len()
+        );
+        for g in &report.gaps {
+            println!("- [{}] {}", severity_for(g.kind.weight()), g.detail);
+        }
+    }
+    Ok(())
+}
+
+/// `task-journal gaps <id> [--fill]` — list gaps, or with `--fill` print the
+/// deterministic gap-fill prompt (embedding the current pack) for the agent.
+fn run_gaps(task_id: &str, fill: bool) -> Result<()> {
+    let (conn, report) = assess_task(task_id)?;
+    if !fill {
+        println!(
+            "honesty score: {}/100 ({} gap(s))",
+            report.score(),
+            report.gaps.len()
+        );
+        for g in &report.gaps {
+            println!("- [{}] {}", severity_for(g.kind.weight()), g.detail);
+        }
+        return Ok(());
+    }
+    let pack = tj_core::pack::assemble(&conn, task_id, tj_core::pack::PackMode::Full)?;
+    match tj_core::completeness::build_gap_fill_prompt(task_id, &report, &pack.text) {
+        Some(prompt) => print!("{prompt}"),
+        None => println!("honesty score: 100/100 — no gaps to fill"),
+    }
+    Ok(())
+}
+
 fn run_export_memory(task: Option<&str>, _all_closed: bool, dry_run: bool) -> Result<()> {
     const MAX_ITEMS: usize = 10;
 

crates/tj-cli/src/main.rs

@@ -143,6 +143,87 @@ fn close_warns_on_completeness_gap() {
         .stdout(contains("status: closed"));
 }
 
+#[test]
+fn check_reports_honesty_score_and_gaps() {
+    let dir = assert_fs::TempDir::new().unwrap();
+    let task_id = String::from_utf8(
+        Command::cargo_bin("task-journal")
+            .unwrap()
+            .env("XDG_DATA_HOME", dir.path())
+            .args(["create", "Check me", "--goal", "ship it"])
+            .assert()
+            .success()
+            .get_output()
+            .stdout
+            .clone(),
+    )
+    .unwrap()
+    .trim()
+    .to_string();
+
+    // A decision with no evidence → DecisionNoEvidence (warn, −3) → 97/100.
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .args(["event", &task_id, "--type", "decision", "--text", "Adopt X"])
+        .assert()
+        .success();
+
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .args(["check", &task_id])
+        .assert()
+        .success()
+        .stdout(contains("honesty score: 97/100"))
+        .stdout(contains("decisions unverified"));
+
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .args(["check", &task_id, "--json"])
+        .assert()
+        .success()
+        .stdout(contains("\"score\": 97"))
+        .stdout(contains("\"severity\": \"warn\""));
+}
+
+#[test]
+fn gaps_fill_emits_targeted_prompt() {
+    let dir = assert_fs::TempDir::new().unwrap();
+    let task_id = String::from_utf8(
+        Command::cargo_bin("task-journal")
+            .unwrap()
+            .env("XDG_DATA_HOME", dir.path())
+            .args(["create", "Fill me", "--goal", "ship it"])
+            .assert()
+            .success()
+            .get_output()
+            .stdout
+            .clone(),
+    )
+    .unwrap()
+    .trim()
+    .to_string();
+
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .args(["event", &task_id, "--type", "decision", "--text", "Adopt X"])
+        .assert()
+        .success();
+
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .args(["gaps", &task_id, "--fill"])
+        .assert()
+        .success()
+        .stdout(contains("Close ONLY these"))
+        .stdout(contains("Add an evidence event"))
+        .stdout(contains("```markdown"));
+}
+
 #[test]
 fn doctor_exits_zero_on_fresh_install() {
     let dir = assert_fs::TempDir::new().unwrap();