heuristic-inbox

What problem does it solve?

Manage curated heuristic-system inbox cases and operation records through the nils-cli heuristic-inbox command.

Core Features & Use Cases

Prereqs:

• heuristic-inbox is installed from the released nils-cli package and available on PATH (>= 1.8.0 for operation-record archive support).
• For runtime-kit shared records, resolve the canonical root before mutating: core/policies/heuristic-system in the active agent-runtime-kit checkout, or AGENT_RUNTIME_HEURISTIC_SYSTEM_ROOT when a workflow exports it. Inputs:
• Shared heuristic-system root, inbox directory, or operation-record path.
• Optional skill-usage record path for new case creation.
• Status transition, archival date, evidence file, or verification request. Outputs:
• Case listing, verification report, new case folder, status update, archived case or operation record, or ingested evidence file.
• Failure modes:
• Case folder layout is invalid.
• Status transition is unsupported or missing required links.
• Evidence path is unreadable or unsafe to retain. Entrypoint:
• Use the released CLI directly: root="${AGENT_RUNTIME_HEURISTIC_SYSTEM_ROOT:-$PWD/core/policies/heuristic-system}" heuristic-inbox list --inbox-dir "$root/error-inbox" --include-archived --format json heuristic-inbox verify "$root/error-inbox/<slug>" --strict --format json heuristic-inbox verify "$root/operation-records/<slug>" --strict --format json heuristic-inbox new --from-skill-usage out/.../skill-usage.record.json --slug pipeline-gap --out-dir "$root/error-inbox" heuristic-inbox set-status "$root/operation-records/<slug>" --status superseded --link "docs/plans/<successor>.md" heuristic-inbox archive "$root/error-inbox/<slug>" --date 2026-05-22

Operation records archive only once superseded/retired with a successor link;

archiving an active record without it fails with archive-failed.

heuristic-inbox set-status "$root/operation-records/<slug>" --status superseded --link "docs/plans/<successor>.md" heuristic-inbox archive "$root/operation-records/<slug>" --date 2026-05-22 heuristic-inbox ingest-evidence "$root/error-inbox/<slug>" --from validation.md

Quick Start

Run heuristic-inbox to list, verify, create, and archive cases in the shared heuristic-system root.

Quick Start

Run heuristic-inbox to list, verify, create, and archive cases in the shared heuristic-system root.