# Heuristic Inbox CLI Graduation Execution State

## Current State

- Status: complete
- Current task: none
- Next task: none
- Last updated: 2026-05-19 CST
- Branch/commit: `feat/heuristic-inbox-cli-graduation`
- Source document: `docs/plans/heuristic-inbox-cli-graduation/heuristic-inbox-cli-graduation-plan.md`

## Task Ledger

| ID | Status | Task | Evidence | Notes |
| --- | --- | --- | --- | --- |
| nils | done | Release `heuristic-inbox` primitive in nils-cli | `heuristic-inbox 0.10.0` on `/opt/homebrew/bin/heuristic-inbox`; `--help` lists `list \| verify \| new \| set-status \| ingest-evidence \| archive \| completion` | Done by user in a separate session; bottle now on the brew tap. Subcommand surface matches the agent-kit schema; JSON payloads use a `{schema_version, command, ok, result}` envelope. |
| T1 | done | Replace skill-local helper with brew-installed CLI | Deleted `bin/heuristic_error_inbox.py` (701 lines) and `scripts/heuristic-error-inbox.sh` (9-line shim); rewrote `SKILL.md` to invoke `heuristic-inbox` directly. Workflow steps 2–5 reference `heuristic-inbox <…>` instead of the shim. | Open-question default applied: thin shim deleted outright in the same PR (no one-minor carry-over). |
| T2 | done | Replace in-repo Python helper tests with CLI smoke | Rewrote `tests/test_workflows_heuristic_system_heuristic_error_inbox.py` to assert: `assert_skill_contract`, command-surface phrases, release-boundary phrases, scope-boundary phrases, `heuristic-inbox --version >= 0.10.0`, and `--help` lists the six subcommands. | Tests skip gracefully when `heuristic-inbox` is not on PATH (mirrors `skill-usage` pattern), so CI without nils-cli does not block. |
| T3 | done | Drop the script-smoke spec for the deleted shim | Deleted `tests/script_specs/skills/workflows/heuristic-system/heuristic-error-inbox/scripts/heuristic-error-inbox.sh.json`. | No new spec added because the brew-installed primitive lives outside this repo. |
| T4 | done | Update cross-doc references | `HEURISTIC_SYSTEM.md`, `heuristic-system/README.md`, `heuristic-system/error-inbox/README.md`, `docs/runbooks/skills/TOOLING_INDEX_V2.md`, `README.md` catalog row, and `tests/test_heuristic_system_docs.py` pin all renamed from `heuristic-error-inbox.sh …` to `heuristic-inbox …` (or to "primitive" wording where the script path was being described). | Plan docs and historical execution-state files left alone — they describe history. |
| T5 | done | Pin nils-cli minimum in DEVELOPMENT.md | `nils-cli >= 0.8.7` bumped to `>= 0.10.0`; tool list now lists `heuristic-inbox` alongside other nils-cli binaries. | Matches the SKILL.md release-boundary section. |
| T6 | done | Validate full repo gate | `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"`: 12 passed; `scripts/check.sh --markdown`: clean; `scripts/check.sh --pre-commit`: 803 passed; `scripts/check.sh --all`: 803 passed (was 831 with the deleted Python helper suite). | No out-of-scope edits leaked. |

## Validation

| Command | Status | Summary | Artifact |
| --- | --- | --- | --- |
| `command -v heuristic-inbox` | pass | `/opt/homebrew/bin/heuristic-inbox` present. | n/a |
| `heuristic-inbox --version` | pass | `heuristic-inbox 0.10.0`, exit 0. | n/a |
| `heuristic-inbox verify heuristic-system/error-inbox/archive/2026/deliver-gitlab-mr-skipped-pipeline-and-cleanup/ --format json` | pass | `ok=true`, `kind=inbox`, `status=promoted` against the migrated archived case. | n/a |
| `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"` | pass | 12 targeted tests passed (incl. CLI smoke + skill-contract + release-boundary). | `/Users/terry/.agents/out/tests/script-coverage/summary.md` |
| `scripts/check.sh --markdown` | pass | Markdown lint passed for 273 files. | n/a |
| `plan-tooling validate --file docs/plans/heuristic-inbox-cli-graduation/heuristic-inbox-cli-graduation-plan.md` | pass | Plan structure validated. | n/a |
| `scripts/check.sh --pre-commit` | pass | Full pre-commit aggregate green; 803 pytest tests passed; stale-skill-scripts audit + entrypoint-ownership audit happy with the helper deletion. | `/tmp/pre-commit-pr3.log` |
| `scripts/check.sh --all` | pass | 803 pytest tests passed; full local gate green. | `/tmp/check-all-pr3.log` |

## Blockers

- None.

## Open Questions Resolved

- `--kind inbox|operation-record` vs nested subcommand namespaces: the
  released primitive ships flat subcommands; the agent-kit skill body
  documents that `new`/`set-status`/`archive` operate on inbox cases and
  `verify` accepts both `ENTRY.md` and `RECORD.md`. No `--kind` flag was
  needed on the released CLI because the case kind is inferred from the file
  name (`ENTRY.md` → inbox, `RECORD.md` → operation record).
- Thin-shim retention vs immediate delete: user chose immediate delete in
  this PR. `scripts/heuristic-error-inbox.sh` and `bin/heuristic_error_inbox.py`
  are removed; the agent-kit skill now points at `heuristic-inbox` on PATH.

## Session Log

### 2026-05-19 CST

- Read:
  - `docs/plans/heuristic-inbox-cli-graduation/heuristic-inbox-cli-graduation-plan.md`
  - `docs/plans/heuristic-inbox-cli-graduation/heuristic-inbox-cli-graduation-discussion-source.md`
  - `skills/tools/workflow-evidence/skill-usage/SKILL.md` (reference for the
    brew-installed CLI documentation pattern)
  - `skills/_shared/python/skill_testing/assertions.py` (to confirm the
    skill-contract scope)
- Edits: see Task Ledger T1–T6.
- Validation: see Validation table.

## Retention Intent

Execution-state for plan delivery; cleanup-eligible after the matching PR
merges and the durable docs reflect the new boundary.
