# Heuristic Case Folder Migration Implementation Handoff

## Status

- Date: 2026-05-19
- Source: User discussion in the current thread covering retained evidence
  pain and the agreed folder migration for inbox + operation records.
- Intended next step: Execute the sibling plan after
  `heuristic-tier2-doc-compression` lands.
- Recommended plan: docs/plans/heuristic-case-folder-migration/heuristic-case-folder-migration-plan.md
- Recommended execution state: docs/plans/heuristic-case-folder-migration/heuristic-case-folder-migration-execution-state.md

## Purpose

Replace the flat-file representation of `heuristic-system/error-inbox/<slug>.md`
and `heuristic-system/operation-records/<slug>.md` with a per-case folder
representation so that the curated record, its redacted evidence, and any
link-to-plan can live together in vcs. Today, an inbox entry links raw
evidence by absolute `out/.../skill-usage.record.json` path; that file is
deleted on local cleanup, and any other curated artefact (redacted excerpt,
screenshot, cmd output) has no in-repo home. The folder layout closes that
gap while keeping the existing "runtime evidence is not automatically a repo
artifact" boundary intact via a strict redaction guardrail in the helper.

## Confirmed Facts

- Today the repo holds one archived inbox entry and one operation record:
  - `heuristic-system/error-inbox/archive/2026/deliver-gitlab-mr-skipped-pipeline-and-cleanup.md`
  - `heuristic-system/operation-records/github-pr-required-check-gating.md`
- Both files reference raw runtime evidence by absolute path under `out/...`;
  those paths are outside vcs and disappear on local cleanup.
- HEURISTIC_SYSTEM.md states the load-bearing rule that "Runtime evidence is
  not automatically a repo artifact — commit only curated evidence or docs
  that project policy expects to retain." This rule must survive the
  migration.
- The helper at
  `skills/workflows/heuristic-system/heuristic-error-inbox/bin/heuristic_error_inbox.py`
  currently expects single-file inbox entries; archive moves are single
  `git mv` operations. Operation records are managed by hand.
- `tests/test_heuristic_system_docs.py` and
  `skills/workflows/heuristic-system/heuristic-error-inbox/tests/...` pin
  several phrases tied to the current single-file shape, including the entry
  template's section list.
- The skill index at `skills/workflows/heuristic-system/README.md` and
  `skills/workflows/plan/durable-artifact-cleanup/SKILL.md` mention
  operation-records paths.
- The Tier 2 plan (`heuristic-tier2-doc-compression`) lands the three-state
  lifecycle before this migration. The folder schema design assumes that
  collapse.

## Decisions

1. Each case becomes a folder: `<slug>/`, containing `ENTRY.md` (the curated
   tracker, matching the current entry template) and an `evidence/` subfolder
   for redacted, curated artifacts only.
2. Plans stay in `docs/plans/<slug>/` under their own lifecycle. A case
   folder may include a single-line `plan-link.md` or a `Plan:` field inside
   `ENTRY.md`, but it must not duplicate plan content.
3. Operation records adopt the same folder shape: `RECORD.md` plus an
   `evidence/` subfolder for validation evidence (test outputs, before/after,
   audit screenshots).
4. The helper gains a redaction guardrail. It refuses to ingest:
   - raw `skill-usage.record.json` files (must be extracted via the helper's
     redaction subcommand first);
   - content matching token-like patterns (`Bearer` headers, `token=`,
     `api_key=`, `-----BEGIN` blocks, etc.);
   - single files above a configurable size limit (default 64 KiB);
   - absolute paths containing `$HOME` segments (rewritten to `<workspace>`
     placeholder).
5. The existing two flat-file artifacts are migrated in the same PR. The
   archived inbox entry keeps its historical lifecycle text; only its
   location and shape change.
6. Helper CLI gains: `new` writes the folder, `ingest-evidence` adds a
   redacted artifact, `archive` moves the whole folder, `verify` checks
   ENTRY.md, evidence redaction, and folder shape.
7. Keep `set-status`, `list`, and `verify` working on the folder shape; the
   commands take the folder path or the `ENTRY.md` path equivalently.

## Scope

- Schema: folder layout for inbox cases and operation-record cases.
- Helper:
  - Update `new`, `set-status`, `list`, `verify`, `archive` to operate on the
    folder shape.
  - Add `ingest-evidence` for adding redacted artifacts.
  - Add a redaction module with the guardrail rules above.
- Docs:
  - `HEURISTIC_SYSTEM.md`: state the folder shape, the redaction boundary,
    and that runtime evidence is still not a repo artifact.
  - `heuristic-system/README.md`: describe the per-subdir folder layout.
  - `heuristic-system/error-inbox/README.md`: entry template moves to
    `ENTRY.md`; describe the `evidence/` subfolder.
  - `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`:
    workflow updates for ingest-evidence and folder-shape archive.
- Tests:
  - Helper tests for folder ops, redaction acceptance/rejection, archive
    moves.
  - Doc tests for the new template and cross-links.
- Migration:
  - Move `heuristic-system/error-inbox/archive/2026/deliver-gitlab-mr-skipped-pipeline-and-cleanup.md`
    to a folder.
  - Move `heuristic-system/operation-records/github-pr-required-check-gating.md`
    to a folder.

## Non-Scope

- nils-cli graduation (separate plan: `heuristic-inbox-cli-graduation`).
- New skill or new lifecycle states; the three-state enum from Tier 2 stays.
- Automatic command-output scraping or shell hooks.
- Changes to `skill-usage.record.v1` schema or `agent-out` paths.
- Promotion of plans into case folders (plans stay in `docs/plans/`).

## Requirements

- The helper rejects raw `skill-usage.record.json` ingestion outright;
  evidence must come through a redaction subcommand that extracts only
  curated fields.
- The redaction guardrail covers token-like patterns, size limits, and
  absolute-path normalization, and is unit-tested.
- `ENTRY.md` keeps the same section list as today's single-file template.
- `RECORD.md` keeps the existing operation-record template sections.
- Existing tests for the entry template and operation-record format pass on
  the migrated files.
- `heuristic-error-inbox.sh archive <folder>` is the only blessed way to move
  a closed entry; bare `git mv` is documented as discouraged.

## Acceptance Criteria

- `heuristic-system/error-inbox/archive/2026/deliver-gitlab-mr-skipped-pipeline-and-cleanup/ENTRY.md`
  exists and validates with the helper.
- `heuristic-system/operation-records/github-pr-required-check-gating/RECORD.md`
  exists and validates.
- `heuristic-error-inbox.sh new --slug <slug>` creates a folder with the
  ENTRY.md scaffold and empty `evidence/`.
- `heuristic-error-inbox.sh ingest-evidence <case> --from-skill-usage <record-dir>`
  rejects unredacted records and accepts redacted excerpts.
- Helper tests pass: folder ops, redaction acceptance and rejection, archive
  move.
- `tests/test_heuristic_system_docs.py` continues to pin the entry template
  section list against `ENTRY.md`.
- `scripts/check.sh --all` passes.

## Validation Plan

- `plan-tooling validate --file docs/plans/heuristic-case-folder-migration/heuristic-case-folder-migration-plan.md`
- `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"`
- `scripts/check.sh --markdown`
- `scripts/check.sh --docs`
- `scripts/check.sh --all`
- Local smoke: create a folder, ingest a redacted excerpt, archive it, verify
  files moved.

## Risks And Guardrails

- A weak redaction guardrail turns `evidence/` into a vcs-tracked log dump.
  Treat redaction failures as `exit 1` and refuse the write; do not warn and
  continue.
- Archiving a folder is `git mv` with an internal tree, which is heavier than
  the current single-file `git mv`. Make sure helper tests cover the
  move-with-children case.
- The Tier 2 lifecycle collapse must land first. Building folder support on
  the legacy five-state enum doubles the test matrix and makes the migration
  brittle.
- Existing tools (`docs-plan-cleanup`, `durable-artifact-cleanup`) reference
  inbox and operation-record paths. Update those references in the same PR
  or document a follow-up.
- The audit value of the existing archived entry depends on its historical
  lifecycle text. Do not rewrite that text during the migration.

## Execution

- Execution state recommendation: docs/plans/heuristic-case-folder-migration/heuristic-case-folder-migration-execution-state.md
- Status: blocked on `heuristic-tier2-doc-compression` landing first.
- Next-task source: docs/plans/heuristic-case-folder-migration/heuristic-case-folder-migration-plan.md

## Retention Intent

This source document is a plan-created coordination artifact. Cleanup-eligible
after the folder migration ships and the durable docs reflect the new shape.

## Open Questions

- Should plans be allowed to live inside a case folder as
  `case/<slug>/plan/` instead of `docs/plans/<slug>/`? Default answer is no,
  but call this out during implementation if a real case appears where a
  plan exists exclusively to serve one inbox entry.
- Should the redaction subcommand be a standalone CLI helper or a flag on
  `ingest-evidence`? Default: a flag, with a documented escape hatch for
  manual review.

## Read-First References

- HEURISTIC_SYSTEM.md
- heuristic-system/README.md
- heuristic-system/error-inbox/README.md
- heuristic-system/error-inbox/archive/2026/deliver-gitlab-mr-skipped-pipeline-and-cleanup.md
- heuristic-system/operation-records/github-pr-required-check-gating.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/tests/test_workflows_heuristic_system_heuristic_error_inbox.py
- skills/workflows/plan/docs-plan-cleanup/SKILL.md
- skills/workflows/plan/durable-artifact-cleanup/SKILL.md
- tests/test_heuristic_system_docs.py
- docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-discussion-source.md
