# Plan: Heuristic Inbox Strict Redaction Alignment

## Overview

Align agent-kit with the released `heuristic-inbox 0.10.2` body redaction
behavior. The change updates current framework docs, the `heuristic-error-inbox`
skill boundary, retained case bodies, and focused tests. Historical PR
bookkeeping and `docs/improvements/` area standardization stay out of scope.

## Read First

- Primary source: `docs/plans/heuristic-inbox-strict-redaction/heuristic-inbox-strict-redaction-review-source.md`
- Source type: review-to-improvement-doc
- Open questions carried into execution: none

## Execution

- Execution state: `docs/plans/heuristic-inbox-strict-redaction/heuristic-inbox-strict-redaction-execution-state.md`

## Scope

- In scope:
  - Update HEURISTIC_SYSTEM docs and tests for `heuristic-inbox 0.10.2`
    body warnings plus `--strict` enforcement.
  - Rewrite retained case body raw-record paths from absolute local home paths
    to `<workspace>/...`.
  - Bump the agent-kit nils-cli minimum from `0.10.1` to `0.10.2` where the
    strict redaction behavior is required.
  - Add focused CLI smoke coverage for strict body redaction.
- Out of scope:
  - The older PR #264 bookkeeping recommendation (`R6`).
  - Standardizing or archiving `docs/improvements/`.
  - Changing the `heuristic-inbox` primitive implementation in nils-cli.

## Assumptions

1. `heuristic-inbox 0.10.2` is the released source of truth for body-level
   redaction behavior.
2. Historical retained cases should preserve audit pointers while redacting
   machine-local prefixes to `<workspace>`.
3. Future implementation follow-ups should be planned under `docs/plans/`
   rather than expanding the current `docs/improvements/` surface.

## Sprint 1: Align Strict Body Redaction

**Goal**: Bring agent-kit docs, retained cases, and tests in line with
`heuristic-inbox 0.10.2`.
**Demo/Validation**:

- Command(s):
  - `heuristic-inbox verify heuristic-system/error-inbox/archive/2026/deliver-gitlab-mr-skipped-pipeline-and-cleanup/ --strict --format json`
  - `heuristic-inbox verify heuristic-system/operation-records/github-pr-required-check-gating/ --strict --format json`
  - `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"`
  - `scripts/check.sh --all`
- Verify:
  - Both retained cases pass strict verification.
  - Focused docs and skill tests pass.
  - Full repo gate passes.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 1.1: Update Current Docs For 0.10.2 Strict Redaction

- **Location**:
  - `HEURISTIC_SYSTEM.md`
  - `heuristic-system/error-inbox/README.md`
  - `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`
  - `docs/improvements/heuristic-system-followup-review.md`
- **Description**: Replace stale "body text is not scanned" wording with the
  released behavior: non-strict verify reports body warnings, and `--strict`
  escalates body findings into violations. Mark the prior R1 gap resolved by
  nils-cli `0.10.2` without changing the older R6 bookkeeping recommendation.
- **Dependencies**:
  - none
- **Complexity**: 3
- **Acceptance criteria**:
  - Current docs no longer claim body-level scanning is absent.
  - Docs explain when to use `heuristic-inbox verify --strict`.
  - The older review makes clear that R1 is resolved while R6 remains outside
    this plan.
- **Validation**:
  - `scripts/check.sh --tests -- -k heuristic_system`

### Task 1.2: Rewrite Retained Case Body Paths

- **Location**:
  - `heuristic-system/error-inbox/archive/2026/deliver-gitlab-mr-skipped-pipeline-and-cleanup/ENTRY.md`
  - `heuristic-system/operation-records/github-pr-required-check-gating/RECORD.md`
- **Description**: Replace absolute local home prefixes in retained body text
  with `<workspace>` placeholders while preserving raw-record pointer shape and
  audit meaning.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 2
- **Acceptance criteria**:
  - Both files contain `<workspace>/out/...` instead of `/Users/...` or
    `/home/...` body paths.
  - `heuristic-inbox verify --strict` succeeds for both retained cases.
- **Validation**:
  - `heuristic-inbox verify heuristic-system/error-inbox/archive/2026/deliver-gitlab-mr-skipped-pipeline-and-cleanup/ --strict --format json`
  - `heuristic-inbox verify heuristic-system/operation-records/github-pr-required-check-gating/ --strict --format json`

### Task 1.3: Pin nils-cli 0.10.2 And Cover Strict Behavior

- **Location**:
  - `DEVELOPMENT.md`
  - `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`
  - `skills/workflows/heuristic-system/heuristic-error-inbox/tests/test_workflows_heuristic_system_heuristic_error_inbox.py`
  - `tests/test_heuristic_system_docs.py`
- **Description**: Raise the minimum nils-cli version to `0.10.2` and add
  tests for the updated release boundary, strict CLI option, and retained case
  body-path redaction.
- **Dependencies**:
  - Task 1.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Version pins and xfail guidance name `0.10.2`.
  - Tests cover `--strict` and body-level absolute home path failures.
  - Focused and full repo gates pass.
- **Validation**:
  - `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"`
  - `scripts/check.sh --all`

## Testing Strategy

- Unit: focused pytest coverage for HEURISTIC_SYSTEM docs and
  `heuristic-error-inbox` skill behavior.
- Integration: `heuristic-inbox verify --strict` against retained inbox and
  operation-record cases.
- E2E/manual: not applicable; this is docs, retained records, and CLI smoke.

## Risks & gotchas

- Historical records are audit evidence; rewrite only machine-local path
  prefixes, not the meaning of the pointer.
- `heuristic-inbox verify` remains non-strict by default for compatibility, so
  tests must explicitly exercise `--strict`.
- Existing older plan execution states may still mention earlier versions as
  history; do not rewrite archival plan history unless it blocks current docs
  or validation.

## Rollback plan

- Revert the docs, tests, plan bundle, and retained path-placeholder edits.
- Reinstall nils-cli `0.10.1` only if the project intentionally drops strict
  body redaction, which is not expected.
