Add v13.3 deterministic reinsert helper handover

handover/workpackages/20260607_1745_v13_3_reinsert_helper.md

@@ -0,0 +1,145 @@
+# Handover — WP7A — v13.3 Deterministic reinsert helper, pure helper and tests
+
+Repository: solidprivacy-nl/scrub  
+Workpackage title: WP7A — v13.3 Deterministic reinsert helper, pure helper and tests  
+Status: implemented; awaiting GitHub Actions and Hugging Face sync
+
+## Summary
+
+WP7A adds the deterministic reinsert helper layer for the future local reinsert workflow.
+
+The helper was already present on `main` during this worker session, so this worker did not overwrite the implementation. This worker inspected the existing files, validated the helper behavior on a reconstructed local subset, and updated project control documentation plus this handover.
+
+The helper supports the future workflow:
+
+```text
+Scrub → Review → Scrub Key → AI → Reinsert → Export → Audit
+```
+
+This workpackage remains helper-only. It does not add UI and does not call AI.
+
+## Files added
+
+- `handover/workpackages/20260607_1745_v13_3_reinsert_helper.md`
+
+## Files changed
+
+- `WORKPACKAGES.md`
+- `CHANGELOG.md`
+
+## Existing implementation files inspected
+
+- `scrub_key_reinsert.py`
+- `tests/test_scrub_key_reinsert.py`
+- `SCRUB_KEY_SPEC.md`
+- `scrub_key.py`
+- `scrub_key_import.py`
+- `tests/test_scrub_key.py`
+- `tests/test_scrub_key_import.py`
+
+## Implemented helper behavior
+
+Existing `scrub_key_reinsert.py` provides:
+
+- `detect_placeholders(text)` for conservative placeholder-token detection.
+- `build_reinsert_mapping(scrub_key)` for deterministic placeholder-to-original mapping.
+- `reinsert_from_scrub_key(text, scrub_key)` for returning reinserted text plus an audit summary.
+
+Behavior covered:
+
+- Valid Scrub Keys can reinsert original values into scrubbed text.
+- Invalid Scrub Keys return validation issues and do not modify text.
+- Duplicate placeholders are detected and excluded from ambiguous reinsertion.
+- Excluded Scrub Key items are ignored even if present in malformed/imported key data.
+- Unknown placeholders in text are reported.
+- Placeholders from the key that are not found in text are reported.
+- Audit summary includes item counts, replacement count, missing placeholders, unknown placeholders, duplicate placeholders, validation issues and reinsert status.
+- Output explicitly records local/no-AI/no-cloud behavior.
+
+## Tests
+
+Existing tests inspected:
+
+- `tests/test_scrub_key_reinsert.py`
+
+Test coverage includes:
+
+- valid reinsert with one placeholder;
+- valid reinsert with multiple placeholders;
+- repeated placeholder occurrences in text;
+- placeholder from key not found in text;
+- unknown placeholder in text not present in key;
+- invalid Scrub Key validation issues;
+- duplicate placeholder detection;
+- excluded rows not being reinserted;
+- synthetic Dutch legal values only;
+- input Scrub Key immutability;
+- explicit no-AI/no-cloud flags;
+- deterministic placeholder detection.
+
+## Validation status
+
+Local targeted validation in this worker environment passed on the available/reconstructed subset:
+
+```bash
+PYTHONPATH=. pytest -q tests/test_scrub_key.py tests/test_scrub_key_import.py tests/test_scrub_key_reinsert.py
+```
+
+Result:
+
+```text
+25 passed
+```
+
+Full repository test suite was not run in this connector environment.
+
+## GitHub Actions status
+
+Pending for the latest WP7A documentation/status commit line.
+
+Existing implementation commits already present on `main` before this worker updated documentation:
+
+- `2f230019de017b80bed42c539fda0d64314338a8` — Add deterministic Scrub Key reinsert helper.
+- `1b58ecf483ba98c3121a059e2c52ca13c3c45d29` — Add deterministic reinsert helper tests.
+
+Documentation/status commits from this worker:
+
+- `8d8bc75edcbe482149e4843b2c686bbc75e14681` — Record WP7A reinsert helper validation.
+- `9209a7a717e0f93781d933e37b82a7ed08e2997b` — Record WP7A reinsert helper validation in changelog.
+
+## Hugging Face sync status
+
+Pending for the latest WP7A documentation/status commit line.
+
+No app behavior changed in this workpackage, so Hugging Face app verification is not required for helper behavior, but sync should still be checked as part of project hygiene.
+
+## App verification status
+
+Not applicable.
+
+No UI was added or changed.
+
+## Boundaries preserved
+
+- No UI added.
+- No edit to `presidio_streamlit.py`.
+- No edit to `fix_streamlit_nested_expanders.py`.
+- No AI calls.
+- No cloud processing.
+- No automatic document rehydration.
+- No TXT, CSV, DOCX or PDF export behavior changes.
+- No Scrub Key export behavior changes.
+- No Scrub Key import UI behavior changes.
+- No secrets, tokens or real personal data stored.
+- Synthetic test data only.
+
+## Remaining risks
+
+- GitHub Actions and Hugging Face sync still need external verification for the latest WP7A documentation/status commits.
+- Reinsert UI is not implemented yet.
+- AI-output reinsert is not implemented yet and should remain a separately reviewed workflow.
+- A Scrub Key remains sensitive because it makes scrubbed values reversible.
+
+## Next recommended step
+
+Verify GitHub Actions and Hugging Face sync for WP7A. After green checks, close WP7A. Then plan a separate v13.3 UI workpackage only after the helper is externally verified.