# Heuristic System Error Inbox

This folder holds versioned summaries of important workflow gaps that were
observed but not fixed in the same turn. It prevents important failures from
being lost when local `out/` evidence is cleaned or unavailable.

This is not a raw log archive — commit only curated, redacted summaries that a
future agent can triage.

For triage rules, retention thresholds, the case layout, and the framework-wide
picture see `HEURISTIC_SYSTEM.md`. This README only covers what an inbox case
must look like, its lifecycle states, and how completed cases leave the active
queue.

## Case Folder Layout

Each active case is a folder directly under this directory:

- `<slug>/ENTRY.md` — the curated tracker (template below).
- `<slug>/evidence/` — optional redacted artifacts written by
  `heuristic-inbox ingest-evidence`. Files here must pass the
  primitive's redaction guardrail (no raw `skill-usage.record.json`, no
  token-like patterns, file size ≤ 64 KiB, no absolute `$HOME` paths).

The primitive's ingest redaction guardrail covers files under
`<slug>/evidence/`. Starting with `heuristic-inbox 0.10.2`, `verify` also
scans `ENTRY.md` and `RECORD.md` body text for absolute `$HOME` paths.
Non-strict verify reports body warnings for historical compatibility;
`verify --strict` escalates those findings into violations. New or updated
entries should pass strict verify before they are committed or reported
complete.

Archived cases keep the same folder shape under `archive/YYYY/<slug>/`.

## Entry Criteria (Summary)

Create an inbox entry when a delivery, release, merge, safety, validation, or
evidence gate produced a gap that was not fixed immediately, when the same
failure class appears more than once, when the user explicitly asks to keep
the issue for later improvement, or when a workaround was used and future
agents need to know the unresolved risk.

Observed CLI, hook, validation, dependency, or workflow friction is important
only when repeated retries, unclear output, docs/behavior mismatch, semantic
workaround, skill-contract relevance, or future-agent reuse value justify
retention. Do not retain a case only because `exit_code != 0`; the full triage
checklist lives in `HEURISTIC_SYSTEM.md`.

Use the `heuristic-error-inbox` workflow skill to create, verify, deduplicate,
triage, update, or archive entries. It delegates deterministic list, verify,
new, set-status, ingest-evidence, and archive operations to the `heuristic-inbox`
primitive.

## Lifecycle

- `open`: gap is known and not yet resolved. Use `Next Action` and linked
  plan, issue, or PR references to express triage progress, ownership, or
  planned work.
- `promoted`: fixed and compressed into an operation record, test, script,
  runbook, or skill policy.
- `wontfix`: explicitly accepted risk.

When a gap is fixed, either update the entry to `promoted` with a link to the
durable fix or move the durable summary into `operation-records/`.

The primitive rejects new writes for legacy lifecycle values (`triaged`,
`planned`); historical entries that still carry them remain readable. Do not
add `archived` as a lifecycle status. A completed entry remains `promoted`
or `wontfix`; archive state is represented by its location under
`heuristic-system/error-inbox/archive/YYYY/` plus an optional `Archive`
section.

An entry is archive-ready only when status is `promoted` or `wontfix`,
durable outcome evidence is linked from the entry or supplied to the archive
command, `Next Action` starts with `None.` and contains no remaining work, and
any unrelated future follow-up has moved to a separate issue, plan, or source
document.

Each top-level folder is an active inbox case. Archived cases keep the same
folder shape under `archive/YYYY/<slug>/` and can be listed explicitly with
the workflow skill.

## Entry Template

The contents of `ENTRY.md` follow this template:

```markdown
# <Short Gap Title>

## Status

- Status: open | promoted | wontfix
- First observed: YYYY-MM-DD
- Area: <skill/script/runbook/tooling>
- Severity: low | medium | high

## Signal

<What failed, in one concise paragraph.>

## Evidence

- Raw record: `<out/.../skill-usage.record.json>`
- Summary: <short command, PR, log, or artifact summary>

## Impact

<Why this matters for future agents or delivery.>

## Current Workaround

<If any.>

## Promotion Criteria

<What would justify a test, script fix, runbook update, skill policy change, or
operation record.>

## Next Action

<One concrete next step.>

## Archive

- Archived: YYYY-MM-DD
- Reason: <why this completed entry left the active inbox>
- Durable link: `<path-or-url>`
```

## Cleanup Rules

`heuristic-system/error-inbox/` is retained evidence, not temporary plan
coordination. Do not remove cases through broad `docs-plan-cleanup` or
durable-artifact cleanup unless the case is promoted, closed, or explicitly
included in the user's cleanup scope. Prefer archiving completed cases over
deleting them; `heuristic-inbox archive` moves the whole case folder
(ENTRY.md plus any redacted `evidence/`) so the curated record stays intact
while the active inbox stays focused on actionable gaps. Bare `git mv` on a
single file is discouraged because it skips the primitive's verify gate.
