chore: add local consistency sync cli

scripts/consistency_check.py

@@ -16,7 +16,7 @@ Checks:
   C-09  workstream-repo-mismatch FAIL  Yes  DB workstream repo_id != file location
   C-10  task-status-drift        WARN  Yes  Task status differs between file and DB
   C-11  task-unlinked            WARN  Yes  Task block has no state_hub_task_id
-  C-12  orphan-db-task           WARN  No   DB task in workstream has no file backing
+  C-12  orphan-db-task           WARN  Yes  DB task in workstream has no file backing unless terminal in a closed workstream
   C-13  workstream-auto-complete WARN  Yes  All DB tasks done but workstream still active
   C-14  ghost-duplicate          WARN  No   Active topic workstream with no repo_id matches a file-backed title — probable ghost from premature create_workstream() call
   C-15  task-db-ahead            WARN  Yes  DB task status is ahead of file — regression prevented; writeback syncs file
@@ -1204,9 +1204,14 @@ def check_repo(api_base: str, repo_slug: str, repo_path_override: str | None = N
             ws_finished = normalise_workstream_status(ws_status) in CLOSED_WORKSTREAM_STATUSES
             for db_t in db_tasks:
                 if db_t["id"] not in file_task_sh_ids:
-                    db_t_status = db_t.get("status", "")
+                    db_t_status = normalise_task_status(db_t.get("status", "todo"))
                     open_task = db_t_status not in TERMINAL_TASK_STATUSES
-                    # Auto-cancel fixable when workstream is finished and task is open
+                    # Closed workstreams can legitimately retain terminal historical
+                    # DB tasks from earlier duplicates. The public task DELETE route
+                    # is a cancel operation, so these are not further actionable.
+                    if ws_finished and not open_task:
+                        continue
+                    # Auto-cancel fixable when workstream is finished and task is open.
                     fixable = ws_finished and open_task
                     report.add(
                         severity="WARN", check_id="C-12",

scripts/install_hooks.sh

@@ -7,8 +7,9 @@
 #   ./install_hooks.sh --repo <slug> --remove # remove hook from one repo
 #   ./install_hooks.sh --all --remove         # remove hook from all repos
 #
-# The hook runs `make fix-consistency REPO=<slug>` in the state-hub after each
-# commit, keeping the hub in sync with workplan file changes automatically.
+# The hook runs `statehub fix-consistency --repo <slug>` after each commit,
+# keeping the hub in sync with workplan file changes automatically. It falls
+# back to the state-hub Make target when the CLI is not installed.
 #
 # Idempotent: the hook block is guarded by a marker comment. Running twice is safe.
 
@@ -79,7 +80,11 @@ install_hook() {
   hook_block=$(cat <<BLOCK
 ${MARKER} — managed by custodian, do not edit this block
 if curl -sf ${API_BASE}/state/health >/dev/null 2>&1; then
-  (cd "${STATEHUB_DIR}" && make fix-consistency REPO=${slug} >/dev/null 2>&1 &)
+  if command -v statehub >/dev/null 2>&1; then
+    (cd "${repo_path}" && statehub fix-consistency --repo ${slug} >/dev/null 2>&1 &)
+  else
+    (cd "${STATEHUB_DIR}" && make fix-consistency REPO=${slug} >/dev/null 2>&1 &)
+  fi
 fi
 ${MARKER}-end
 BLOCK

scripts/project_rules/agents-codex.template

@@ -98,12 +98,12 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
 **Close:**
 1. Update workplan file task statuses to reflect progress
 2. Log: `POST /progress/` with a summary of what changed
-3. Note for the custodian operator: after workplan file changes, run from
-   `~/state-hub`:
+3. After workplan file changes, run:
    ```bash
-   make fix-consistency REPO={REPO_SLUG}
+   statehub fix-consistency
    ```
-   This syncs task status from files into the hub DB.
+   Coding agents should run this directly; ask the operator only if the CLI or
+   State Hub API is unavailable. This syncs task status from files into the hub DB.
 
 ---
 
@@ -172,5 +172,5 @@ Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blo
 
 To create a new workplan:
 1. Write the file following the format above
-2. Notify the custodian operator to run `make fix-consistency REPO={REPO_SLUG}`
-   (or send a message to the hub agent via `POST /messages/`)
+2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or
+   State Hub API is unavailable.

scripts/project_rules/session-protocol.template

@@ -70,15 +70,16 @@ curl -s -X POST http://127.0.0.1:8000/progress/ \
   -H "Content-Type: application/json" \
   -d '{"topic_id":"{TOPIC_ID}","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
 ```
-If workplan files were modified, ensure the local copy is up to date first:
+If workplan files were modified, ensure the local copy is up to date first,
+then sync from the repo checkout:
 ```bash
-git -C <repo_path> pull --ff-only
-cd ~/state-hub && make fix-consistency REPO={REPO_SLUG}
+git pull --ff-only
+statehub fix-consistency
 ```
 For repos where implementation runs on a remote machine (e.g. CoulombCore),
-use the combined target which pulls before fixing:
+use the pull-before-fix mode from any shell with the State Hub CLI:
 ```bash
-cd ~/state-hub && make fix-consistency-remote REPO={REPO_SLUG}
+statehub fix-consistency --repo {REPO_SLUG} --remote
 ```
 **C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
 will sync the file to match DB.  **C-16** (repo behind remote) blocks all writes