# Heuristic Inbox CLI Graduation Implementation Handoff

## Status

- Date: 2026-05-19
- Source: User discussion in the current thread covering the proposal to
  graduate the agent-kit heuristic-system helper into a nils-cli primitive.
- Intended next step: Execute the sibling plan after
  `heuristic-case-folder-migration` lands.
- Recommended plan: docs/plans/heuristic-inbox-cli-graduation/heuristic-inbox-cli-graduation-plan.md
- Recommended execution state: docs/plans/heuristic-inbox-cli-graduation/heuristic-inbox-cli-graduation-execution-state.md

## Purpose

Promote the heuristic-system inbox + operation-record helper from a skill-local
script in agent-kit into a versioned nils-cli primitive named
`heuristic-inbox`. Agents in any repo (agent-kit, codex sessions, downstream
projects) can then operate retained workflow cases through a single installed
CLI. The skill body in agent-kit shrinks to a thin workflow shell that
delegates deterministic ops to the CLI and keeps the judgment surface. The CLI
also captures execution logs to an `agent-out` topic so future agents can
audit prior invocations.

## Confirmed Facts

- nils-cli already hosts deterministic primitives that agent-kit consumes:
  `agent-docs`, `plan-tooling`, `skill-usage`, `agent-out`, `api-*`,
  `semantic-commit`. They are installed via `brew install nils-cli` from the
  `sympoies/tap`.
- The agent-kit helper at
  `skills/workflows/heuristic-system/heuristic-error-inbox/bin/heuristic_error_inbox.py`
  is ~700 lines of Python and is invoked through a 9-line shell shim at
  `skills/workflows/heuristic-system/heuristic-error-inbox/scripts/heuristic-error-inbox.sh`.
- After `heuristic-case-folder-migration` ships, the helper will own folder
  schema enforcement and redaction. Both are deterministic responsibilities
  that match the nils-cli scope.
- nils-cli primitives default to writing run evidence under
  `agent-out project --topic <name> --mkdir` directories.
- The skill body owns judgment that does not belong in a primitive: "should
  this case be retained?", "what should the entry body say?", "promote vs
  archive?".
- The Tier 2 lifecycle compression is already shipped before this plan can
  start; the CLI surface assumes the three-state enum.

## Decisions

1. The graduated CLI is named `heuristic-inbox`. Both inbox and
   operation-record cases route through this one CLI with a `--kind` or
   subcommand selector.
2. nils-cli owns: schema validation, folder ops, redaction guardrail,
   lifecycle state transitions, archive moves, execution-log capture.
3. agent-kit owns: the `heuristic-error-inbox` skill body, the judgment
   workflow, doc cross-links to HEURISTIC_SYSTEM.md, and the case content
   itself.
4. The graduation does not change schema. Folder shape, ENTRY.md / RECORD.md
   templates, and redaction rules are imported from agent-kit as-is.
5. agent-kit removes the in-repo Python helper after the nils-cli release is
   tagged. The 9-line shim becomes a thin wrapper that calls `heuristic-inbox`
   and adds no logic.
6. Execution logs are written to
   `out/projects/<repo>/<ts>-heuristic-inbox/invocation.json` (and supporting
   files) on every write op. The skill body links them when retained
   evidence is required.
7. nils-cli release is a minor bump (no breaking changes to existing
   primitives). Skill body upgrade in agent-kit pins the minimum nils-cli
   version.

## Scope

- nils-cli (separate repo):
  - New primitive crate/module `heuristic-inbox`.
  - Port helper logic from agent-kit (schema, redaction, folder ops,
    lifecycle).
  - Add execution-log capture matching the `skill-usage` pattern.
  - Tests, packaging, version bump, brew tap publish.
- agent-kit:
  - Update `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`
    to call the brew-installed CLI.
  - Delete `bin/heuristic_error_inbox.py` and shrink the shim to a thin
    wrapper.
  - Remove the in-repo Python tests and replace them with a smoke that
    confirms the CLI is on PATH and reports the expected version.
  - Update `DEVELOPMENT.md` prereqs to require `nils-cli >= <new version>`.
  - Update SKILL_USAGE_RECORDING_V1.md or related runbook references that
    name the old in-repo helper.

## Non-Scope

- Schema changes beyond the folder shape from
  `heuristic-case-folder-migration`.
- Lifecycle enum changes beyond Tier 2.
- Adding judgment to the CLI (no policy decisions inside the primitive).
- Other heuristic-* skills beyond the existing `heuristic-error-inbox`.
- Migrating other agent-kit skill helpers to nils-cli (separate scope).

## Requirements

- `heuristic-inbox --version` reports a semver string and exits 0.
- All deterministic ops have schema-validated input and exit codes documented
  the same way other nils-cli primitives are (`0` success, `2` usage, `1`
  validation/op failure, `64` redaction rejected).
- Execution logs land under `out/projects/<repo>/<ts>-heuristic-inbox/` and
  always include `invocation.json` with the command, args, exit code, repo
  context, and timing.
- The skill body in agent-kit performs no deterministic work that would
  rightly live in the primitive.
- Agent-kit `scripts/check.sh --all` passes after the in-repo helper is
  removed.

## Acceptance Criteria

- nils-cli release tagged and available via `brew upgrade nils-cli`.
- `heuristic-inbox --help` lists subcommands matching the agent-kit
  schema: `new`, `list`, `verify`, `set-status`, `archive`,
  `ingest-evidence`.
- `heuristic-error-inbox` skill body in agent-kit calls `heuristic-inbox`
  exclusively for deterministic ops.
- `skills/workflows/heuristic-system/heuristic-error-inbox/bin/` is removed
  and tracked tests no longer import the Python module.
- Smoke test in agent-kit confirms `heuristic-inbox` on PATH with the
  required minimum version.
- `DEVELOPMENT.md` pins the new minimum.
- `scripts/check.sh --all` passes after both repos land.

## Validation Plan

- nils-cli side: project's own `cargo test`/`uv run pytest` (whichever the
  repo uses), plus the existing release smoke.
- agent-kit side:
  - `plan-tooling validate --file docs/plans/heuristic-inbox-cli-graduation/heuristic-inbox-cli-graduation-plan.md`
  - `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"`
  - `scripts/check.sh --markdown`
  - `scripts/check.sh --all`
  - Local smoke: `heuristic-inbox new --from-skill-usage <record> --slug pilot`
    followed by `verify` and `archive` against a fresh sandbox folder.
    (Originally written as `--slug pilot --kind inbox`; resolved
    post-execution — see Open Questions below.)

## Risks And Guardrails

- A bug in the CLI cannot be hotfixed inside agent-kit anymore. The fix
  requires a nils-cli release before any consumer can pick it up. Mitigate
  by keeping the agent-kit fallback shim able to invoke an explicit
  `NILS_CLI_BIN` override for local development of the CLI.
- A schema drift between agent-kit `ENTRY.md` template and the nils-cli
  enforced shape would break every case. The schema migration must happen
  first (`heuristic-case-folder-migration`) and the CLI must consume the
  same schema fixtures.
- Judgment leaking into the CLI defeats the boundary. Keep policy in the
  skill body and reject CLI additions like "auto-promote when X conditions
  met".
- The brew tap release lag means installing on a fresh box requires waiting
  for the bottle. Document the manual checkout fallback in DEVELOPMENT.md.
- Removing the in-repo helper before the brew release is published would
  break existing skill invocations. Sequence the change as: nils-cli
  release tag -> agent-kit PR that depends on the new minimum.

## Execution

- Execution state recommendation: docs/plans/heuristic-inbox-cli-graduation/heuristic-inbox-cli-graduation-execution-state.md
- Status: blocked on `heuristic-case-folder-migration` shipping first.
- Next-task source: docs/plans/heuristic-inbox-cli-graduation/heuristic-inbox-cli-graduation-plan.md

## Retention Intent

This source document is a plan-created coordination artifact. Cleanup-eligible
after the graduation lands and DEVELOPMENT.md / SKILL.md reflect the new
boundary.

## Open Questions

- `--kind inbox|operation-record` vs separate subcommand namespaces
  (`heuristic-inbox inbox new`, `heuristic-inbox op-record new`). Default
  recommendation is `--kind` to keep the CLI surface flat; revisit if the
  two case types diverge.
- Whether to keep the agent-kit shim at all after the graduation, or to
  document `heuristic-inbox` as the canonical entry point and drop the shim.
  Default: keep a thin shim for one minor release, then delete.

### Resolved Post-Execution (2026-05-19)

- The released CLI dropped `--kind` entirely. Case kind is inferred from the
  `ENTRY.md` (inbox) or `RECORD.md` (operation record) filename inside the
  case folder; `heuristic-inbox verify` returns `kind: inbox|record`
  accordingly. The agent-kit skill body never exposed `--kind` to the
  judgment workflow, so no policy surface was lost.
- The shim (`scripts/heuristic-error-inbox.sh`) was deleted in the same PR
  rather than carried for one minor release. The skill body now points at the
  brew-installed primitive directly. Reversibility is preserved by reverting
  PR #264; no consumer still depends on the shim path.
- Implementation evidence:
  `docs/plans/heuristic-inbox-cli-graduation/heuristic-inbox-cli-graduation-execution-state.md`
  "Open Questions Resolved".

## Read-First References

- HEURISTIC_SYSTEM.md
- skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md
- skills/workflows/heuristic-system/heuristic-error-inbox/bin/heuristic_error_inbox.py
- skills/workflows/heuristic-system/heuristic-error-inbox/scripts/heuristic-error-inbox.sh
- skills/workflows/heuristic-system/heuristic-error-inbox/tests/test_workflows_heuristic_system_heuristic_error_inbox.py
- skills/tools/workflow-evidence/skill-usage/SKILL.md
- DEVELOPMENT.md
- docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md
- docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-discussion-source.md
- docs/plans/heuristic-case-folder-migration/heuristic-case-folder-migration-discussion-source.md
