prettyplay 0.0.2__tar.gz → 0.0.3__tar.gz

{prettyplay-0.0.2 → prettyplay-0.0.3}/.goga/Dockerfile

@@ -9,6 +9,8 @@ COPY agents/product.sh /home/goga/bin/product-as-claude.sh
 COPY agents/manager.sh /home/goga/bin/manager-as-claude.sh
 COPY agents/analyst.sh /home/goga/bin/analyst-as-claude.sh
 COPY agents/tester.sh /home/goga/bin/tester-as-claude.sh
+COPY agents/tech-writer.sh /home/goga/bin/tech-writer-as-claude.sh
+COPY agents/planner.sh /home/goga/bin/planner-as-claude.sh
 
 RUN chmod +x /home/goga/bin/*.sh
 

prettyplay-0.0.3/.goga/history/2026/fix-step-cache/acceptance.md

@@ -0,0 +1,329 @@
+# Final Acceptance Report
+
+## Summary
+Audited the fix-step-cache branch against 0.0.x across six cells. Verified contracts, runtime facade exports, cell usage examples and behavioral test coverage. Fixed the sweep directory-inspection exception leak, repaired four usage documents and added 13 parameterized regression/boundary cases. The final full suite passes: 1378 tests, no failures or skips.
+
+## Acceptance Scope
+| Cell | Change types |
+|---|---|
+| prettyplay | CODE / MANIFEST / USAGE / TEST |
+| prettyplay/cache | CODE / MANIFEST / USAGE / TEST |
+| prettyplay/engine | CODE / MANIFEST / USAGE / TEST |
+| prettyplay/engine/groups | CODE / MANIFEST / USAGE / TEST |
+| prettyplay/engine/renderer | CODE / MANIFEST / USAGE / TEST |
+| prettyplay/engine/steering | CODE / MANIFEST / TEST |
+
+Functionality: rendered-value addressing, NFC plus trim, verbatim capture-tag metadata, fresh group-recovery identities, touched working sets and guarded close-time cleanup. Scope was resolved from the branch diff and completed build history. The pre-existing completed-plan relocation is excluded from this acceptance commit.
+
+## CODEMANIFEST Status
+CONSISTENT for the scoped functionality. Zero manifest updates. `goga lint`: 12 cells, zero errors. All six `goga contract` comparisons were reviewed; runtime signature/member checks resolved the static extractor's Pydantic and embedding limitations. All declared locations and facade exports exist; baseline conventions and annotations are present.
+
+## Usages Status
+CONSISTENT after four cell-level updates. Generation/healing examples now carry a real render product with addressing_text; cache storage constructs a matching identity; recovery examples retain both texts. Stale casefold terminology was replaced by NFC plus trim. All Python usage snippets compile; core cache, engine and renderer examples execute with temporary storage and fake external boundaries. Shared project practices remain unchanged.
+
+## Test Coverage Assessment
+ADEQUATE. 1378 passed, zero failed/errors/skipped on Python 3.12.15. Statement coverage: 99.61% (2536/2546); branch coverage: 97.88% (599/612); combined: 99.27%. Renderer combined coverage improved from 88% to 96%. The cache store has 100% statement coverage; generator, healer, steering and executor have 100% combined coverage. Ruff lint and formatting pass for all 122 source/test files.
+
+## Critical Findings
+| Source | Finding | Status |
+|---|---|---|
+| Manifest / implementation | sweep_untouched called Path.is_dir outside its OSError handler, allowing PermissionError to violate its never-raises guarantee | Fixed after q1 approval; inspection and enumeration errors now return an empty result, preserve files and log one contextual warning |
+
+## Warnings
+| Source | Finding | Recommendation |
+|---|---|---|
+| Test | Newly introduced scanner comment/quote/malformed-source boundaries lacked tests | Resolved after q2 approval: 11 parameterized public-API cases added |
+| Usage | Generation/healing examples omitted addressing_text and still described casefold normalization | Resolved in four cell-level usage files |
+| Tooling (INFO) | Static contract extraction does not fully represent Pydantic constructors and embedded members | Runtime signatures, model_fields and provider exports were verified |
+
+## Applied Updates
+- prettyplay/cache/store.py
+- prettyplay/cache/.usages/storage.md
+- prettyplay/engine/.usages/generation.md
+- prettyplay/engine/.usages/healing.md
+- prettyplay/engine/groups/.usages/recovery.md
+- tests/cache/test_store.py
+- tests/engine/renderer/test_render.py
+- .goga/history/2026/fix-step-cache/acceptance.md
+
+No CODEMANIFEST changes or shared-practice edits were required. q1 approved the code repair and regression test; q2 approved additional renderer boundary tests.
+
+## Risks
+| Risk | Severity | Mitigation |
+|---|---|---|
+| Tests fake external browser/provider boundaries | INFO | Existing wired integration coverage exercises real cache/engine/executor composition; no live service validation is claimed |
+| Not every internal branch is covered | INFO | Remaining renderer lines are the overridden base parser; changed public paths and scanner boundaries are tested. Raw coverage artifacts retain the precise residual list |
+| Cache addresses change on upgrade, and default cleanup removes untouched same-key entries | Expected behavior | Existing migration and cleanup=False guidance is preserved and audited |
+
+## Verdict
+ACCEPTED_WITH_NOTES. All five acceptance gates passed after the confirmed repairs. No open critical findings or warning coverage gaps remain. Notes concern measurement/tooling limitations and the absence of a live external-service run.
+
+---
+
+# Acceptance Scope Report
+
+## Data source
+Branch fix-step-cache versus configured base 0.0.x (46 changed files); build history and completed implementation plan identify the functionality. The pre-existing worktree change moves the completed plan and is excluded from audit edits.
+
+## Functionality
+Rendered-sentence cache addressing, verbatim metadata, per-test touched set and guarded close-time cleanup.
+
+## Cells for acceptance
+| Cell | Path | Change types |
+|---|---|---|
+| prettyplay | prettyplay | CODE / MANIFEST / TEST / USAGE |
+| prettyplay/cache | prettyplay/cache | CODE / MANIFEST / TEST / USAGE |
+| prettyplay/engine | prettyplay/engine | CODE / MANIFEST / TEST |
+| prettyplay/engine/groups | prettyplay/engine/groups | CODE / MANIFEST / TEST / USAGE |
+| prettyplay/engine/renderer | prettyplay/engine/renderer | CODE / MANIFEST / TEST / USAGE |
+| prettyplay/engine/steering | prettyplay/engine/steering | CODE / MANIFEST / TEST |
+
+## Affected dependencies
+| Dependent cell | Dependency type | Impact assessment |
+|---|---|---|
+| prettyplay | DIRECT | Consumes prettyplay/cache, prettyplay/engine, prettyplay/engine/groups, prettyplay/engine/renderer, prettyplay/engine/steering; included in scope. |
+| prettyplay/engine | DIRECT | Consumes prettyplay/cache, prettyplay/engine/renderer; included in scope. |
+| prettyplay/engine/groups | DIRECT | Consumes prettyplay/cache, prettyplay/engine, prettyplay/engine/renderer; included in scope. |
+| prettyplay/engine/steering | DIRECT | Consumes prettyplay/cache, prettyplay/engine, prettyplay/engine/renderer; included in scope. |
+
+Transitive paths converge on prettyplay through engine/groups/steering; no additional out-of-scope consumer cells.
+
+## Scope summary
+Six cells; 46 branch-changed files: CODE=10, MANIFEST=6, OTHER=10, TEST=13, USAGE=7. All six manifests and usage directories exist.
+
+
+---
+
+# Manifest Review Report
+
+## Linter Results
+All 12 cells PASS with zero errors. Six goga contract outputs retained in reports/.
+
+## Analysis 1 — Code vs Requirements
+| Cell | Signature Match | Method Coverage | Property Coverage | Facade | Status |
+|---|---|---|---|---|---|
+| prettyplay | Match | Complete | Complete | Present | PASS |
+| prettyplay/cache | Match | Complete | Complete | Present | PASS |
+| prettyplay/engine | Match | Complete | Complete | Present | PASS |
+| prettyplay/engine/groups | Match | Complete | Complete | Present | PASS |
+| prettyplay/engine/renderer | Match | Complete | Complete | Present | PASS |
+| prettyplay/engine/steering | Match | Complete | Complete | Present | PASS |
+
+Runtime inspect.signature, model_fields and provider facade checks resolve static extractor limitations for Pydantic constructors and embedded exports. Semantic return labels and Config/PrettyConfig aliases do not change the API.
+
+## Analysis 2 — Requirements vs Code
+| Cell | Undocumented Entities | Description Accuracy | Annotation Quality | Status |
+|---|---|---|---|---|
+| prettyplay | No missing facade declarations | Changed behavior matches | Actionable changed contracts | PASS |
+| prettyplay/cache | No missing facade declarations | Changed behavior matches | Actionable changed contracts | PASS |
+| prettyplay/engine | No missing facade declarations | Changed behavior matches | Actionable changed contracts | PASS |
+| prettyplay/engine/groups | No missing facade declarations | Changed behavior matches | Actionable changed contracts | PASS |
+| prettyplay/engine/renderer | No missing facade declarations | Changed behavior matches | Actionable changed contracts | PASS |
+| prettyplay/engine/steering | No missing facade declarations | Changed behavior matches | Actionable changed contracts | PASS |
+
+## Algorithm Consistency
+- prettyplay: verified — render before cache lookup; identity from addressing_text; teardown before guarded cleanup; cleanup=False preserves entries.
+- prettyplay/cache: verified — NFC then strip; construction invariant; successful loads/saves touch; ownership-filtered sweep now guards scope inspection.
+- prettyplay/engine: verified — generation, regeneration and funded healing store current addressing_text after validation/compliance.
+- prettyplay/engine/groups: verified — re-render each row; fresh identity and healing budget; preserve original trace records.
+- prettyplay/engine/renderer: verified — single render and snapshot; original source spans restored; collision detection; inputs and memory separated.
+- prettyplay/engine/steering: verified — engineer-approved successful turn validates and passes compliance before publication and addressing write-back.
+
+## Operational Flow Consistency
+- prettyplay: verified — render before cache lookup; identity from addressing_text; teardown before guarded cleanup; cleanup=False preserves entries.
+- prettyplay/cache: verified — NFC then strip; construction invariant; successful loads/saves touch; ownership-filtered sweep now guards scope inspection.
+- prettyplay/engine: verified — generation, regeneration and funded healing store current addressing_text after validation/compliance.
+- prettyplay/engine/groups: verified — re-render each row; fresh identity and healing budget; preserve original trace records.
+- prettyplay/engine/renderer: verified — single render and snapshot; original source spans restored; collision detection; inputs and memory separated.
+- prettyplay/engine/steering: verified — engineer-approved successful turn validates and passes compliance before publication and addressing write-back.
+
+## Guarantee Verification
+- prettyplay: verified — render before cache lookup; identity from addressing_text; teardown before guarded cleanup; cleanup=False preserves entries.
+- prettyplay/cache: verified — NFC then strip; construction invariant; successful loads/saves touch; ownership-filtered sweep now guards scope inspection.
+- prettyplay/engine: verified — generation, regeneration and funded healing store current addressing_text after validation/compliance.
+- prettyplay/engine/groups: verified — re-render each row; fresh identity and healing budget; preserve original trace records.
+- prettyplay/engine/renderer: verified — single render and snapshot; original source spans restored; collision detection; inputs and memory separated.
+- prettyplay/engine/steering: verified — engineer-approved successful turn validates and passes compliance before publication and addressing write-back.
+
+## Practice Consistency
+- prettyplay: verified — render before cache lookup; identity from addressing_text; teardown before guarded cleanup; cleanup=False preserves entries.
+- prettyplay/cache: verified — NFC then strip; construction invariant; successful loads/saves touch; ownership-filtered sweep now guards scope inspection.
+- prettyplay/engine: verified — generation, regeneration and funded healing store current addressing_text after validation/compliance.
+- prettyplay/engine/groups: verified — re-render each row; fresh identity and healing budget; preserve original trace records.
+- prettyplay/engine/renderer: verified — single render and snapshot; original source spans restored; collision detection; inputs and memory separated.
+- prettyplay/engine/steering: verified — engineer-approved successful turn validates and passes compliance before publication and addressing write-back.
+
+## Baseline Usages/Annotations Audit
+| Cell | Baseline Usages present? | Baseline Annotations present? |
+|---|---|---|
+| prettyplay | Yes | Yes |
+| prettyplay/cache | Yes | Yes |
+| prettyplay/engine | Yes | Yes |
+| prettyplay/engine/groups | Yes | Yes |
+| prettyplay/engine/renderer | Yes | Yes |
+| prettyplay/engine/steering | Yes | Yes |
+
+## Findings
+| Cell | Analysis | Finding | Severity | Proposed Action |
+|---|---|---|---|---|
+| prettyplay/cache | Guarantee | is_dir PermissionError escaped sweep_untouched | CRITICAL, FIXED | Move directory check inside handler and regress; approved q1 |
+| Tooling | Extraction | Pydantic/embedding static extraction incomplete | INFO | Runtime checks passed |
+
+## Applied Updates
+| Cell | Updated Section | Previous Value | New Value | Reason |
+|---|---|---|---|---|
+| prettyplay/cache | store.py | is_dir outside try | is_dir inside OSError handler | Never-raises contract |
+| prettyplay/cache | tests/cache/test_store.py | No scope access regression | is_dir/iterdir parameterized regression | Preserve files and log warning |
+
+## Critical Discrepancies
+None open. The reproduced issue was repaired after q1 approval and this gate was repeated. No CODEMANIFEST changes.
+
+## Overall Status
+CONSISTENT for the scoped functionality after repair. Store regression suite: 43 passed. Changed-file lint and format passed.
+
+
+---
+
+# Usage Review Report
+
+## Cell-level usages
+| Cell | Usage file | Examples valid? | Descriptions accurate? | Names aligned? | Updated? |
+|---|---|---|---|---|---|
+| prettyplay | prettyplay/.usages/lifecycle.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | No |
+| prettyplay | prettyplay/.usages/steps.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | No |
+| prettyplay/cache | prettyplay/cache/.usages/addressing.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | No |
+| prettyplay/cache | prettyplay/cache/.usages/budgets.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | No |
+| prettyplay/cache | prettyplay/cache/.usages/storage.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | Yes |
+| prettyplay/engine | prettyplay/engine/.usages/generation.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | Yes |
+| prettyplay/engine | prettyplay/engine/.usages/healing.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | Yes |
+| prettyplay/engine/groups | prettyplay/engine/groups/.usages/recovery.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | Yes |
+| prettyplay/engine/renderer | prettyplay/engine/renderer/.usages/memory.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | No |
+| prettyplay/engine/renderer | prettyplay/engine/renderer/.usages/rendering.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | No |
+| prettyplay/engine/renderer | prettyplay/engine/renderer/.usages/validation.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | No |
+| prettyplay/engine/steering | prettyplay/engine/steering/.usages/steering.md | Yes, compile/API review; executable core examples exercised | Yes after updates | Yes | No |
+
+Browser and interactive examples were checked against signatures/implementation rather than launched against an external site. Store/generation/healing examples were executed against a temporary cache and fake page/provider. Renderer/memory/validation examples ran directly.
+
+## Project usages — remarks
+| Usage file | Referenced by cells | Remark | Type |
+|---|---|---|---|
+| conventions.md | All six | Loaded and applied; no shared practice edits | None |
+| cooks/jinja.md | renderer | Single-render/source-tag policy matches implementation | None |
+| prompts/step_generation.md, step_cheatsheet.md, group_framing.md, group_diagnosis.md | engine, groups, steering | Read with implementation prompt mirrors; no scoped discrepancies identified | None |
+
+## Integrity
+| Cell | All Usages have files? | All imported usages exist? | All usages referenced in annotations? |
+|---|---|---|---|
+| prettyplay | Yes | Yes | Yes |
+| prettyplay/cache | Yes | Yes | Yes |
+| prettyplay/engine | Yes | Yes | Yes |
+| prettyplay/engine/groups | Yes | Yes | Yes |
+| prettyplay/engine/renderer | Yes | Yes | Yes |
+| prettyplay/engine/steering | Yes | Yes | Yes |
+
+## Applied updates
+| Usage file | Change | Reason |
+|---|---|---|
+| cache/.usages/storage.md | Construct matching identity and addressing text; supply step code | Self-contained cache construction respecting invariant |
+| engine/.usages/generation.md | render_step + matching identity; NFC/trim terminology | Previously empty addressing_text failed successful store |
+| engine/.usages/healing.md | render_step and current addressing text; NFC/trim terminology | Correct healed write-back metadata |
+| engine/groups/.usages/recovery.md | Actual render product | Keep both texts in caller example |
+
+## Uncovered patterns
+No undocumented key pattern identified for the changed addressing and cleanup surface.
+
+## Overall consistency
+CONSISTENT after four cell-level usage updates. Shared practices unchanged. goga lint passes all 12 cells with zero errors.
+
+
+---
+
+# Test Assessment Report
+
+## Coverage Points
+| Cell | Coverage Point | Type | Source |
+|---|---|---|---|
+| prettyplay/cache | NFC plus trim preserves case, internal spaces, template data; empty input | contract / boundary | CODEMANIFEST / code |
+| prettyplay/cache | CachedStep addressing invariant and valid construction | contract / boundary | CODEMANIFEST / code |
+| prettyplay/cache | Identity hash and budget accounting | contract / branch | CODEMANIFEST / code |
+| prettyplay/cache | Verbatim STEP_TEXT round trip and normalized comparison | contract / integration | CODEMANIFEST / code |
+| prettyplay/cache | Only successful load/save touches; skipped writes and misses do not | contract / branch | CODEMANIFEST / code |
+| prettyplay/cache | Unreadable metadata preserves file and warns | boundary / integration | CODEMANIFEST / code |
+| prettyplay/cache | Foreign and non-digest files survive; sweep idempotent | contract / boundary | CODEMANIFEST / code |
+| prettyplay/cache | Scope inspection/enumeration permission errors preserve files and warn | contract / boundary | CODEMANIFEST / code |
+| prettyplay/engine/renderer | Frozen PreparedStep, four fields and defaults | contract | CODEMANIFEST / code |
+| prettyplay/engine/renderer | One snapshot, one evaluation, both outputs | contract / branch | CODEMANIFEST / code |
+| prettyplay/engine/renderer | Capture source preservation and inactive branches | contract / boundary | CODEMANIFEST / code |
+| prettyplay/engine/renderer | Substituted Jinja text remains literal | contract / boundary | CODEMANIFEST / code |
+| prettyplay/engine/renderer | Marker collision raises loudly | contract / boundary | CODEMANIFEST / code |
+| prettyplay/engine/renderer | Comments, escaped quotes/backslashes do not shift source spans | boundary | CODEMANIFEST / code |
+| prettyplay/engine/renderer | Unterminated expressions, comments and raw blocks fail before execution | boundary | CODEMANIFEST / code |
+| prettyplay/engine/renderer | Snapshot isolation and atomic accepted publication | contract | CODEMANIFEST / code |
+| prettyplay/engine/renderer | Exact result keys, string/nonblank values; no fabricated captures | contract / boundary | CODEMANIFEST / code |
+| prettyplay/engine | Generation stores current addressing_text | contract / integration | CODEMANIFEST / code |
+| prettyplay/engine | Healing uses current render rather than old metadata | contract / integration | CODEMANIFEST / code |
+| prettyplay/engine/groups | Fresh render identity and healing refresh; trace key retained | contract / integration | CODEMANIFEST / code |
+| prettyplay/engine/groups | Re-render sees earlier row publication and keeps caller traces unchanged | integration / branch | CODEMANIFEST / code |
+| prettyplay/engine/steering | Successful guided write-back preserves addressing text | contract / integration | CODEMANIFEST / code |
+| prettyplay | Executor evaluates each step once | contract / integration | CODEMANIFEST / code |
+| prettyplay | Rendered values produce distinct caches and prevent cross-value replay | integration | CODEMANIFEST / code |
+| prettyplay | Plain and equivalent template share one cache address | integration | CODEMANIFEST / code |
+| prettyplay | Close preserves working set, removes own untouched files, cleanup=False preserves all | integration | CODEMANIFEST / code |
+| prettyplay | Teardown failure wins; unexpected sweep error is guarded | contract / branch | CODEMANIFEST / code |
+| prettyplay | Strict template replay validates and publishes without generation | integration | CODEMANIFEST / code |
+
+## Existing Tests
+The complete executed test inventory is in test-inventory.md (1378 cases, including parameterizations, with file, classification and status). Named evidence for scoped guarantees follows.
+
+## Coverage Assessment
+| Coverage Point | Covered by Test? | Test | Test Type | Coverage Completeness |
+|---|---|---|---|---|
+| NFC plus trim preserves case, internal spaces, template data; empty input | Yes | tests.cache.test_text.TestNormalizeStepTextContract.test_normalize_step_text_is_importable_from_facade | CONTRACT | Adequate, including representative failure paths |
+| CachedStep addressing invariant and valid construction | Yes | tests.cache.test_models.TestCachedStepContract.test_cached_step_holds_identity_addressing_code_and_created_at | CONTRACT | Adequate, including representative failure paths |
+| Identity hash and budget accounting | Yes | tests.cache.test_budgets.TestRunBudgetsContract.test_run_budgets_is_importable_from_facade | CONTRACT | Adequate, including representative failure paths |
+| Verbatim STEP_TEXT round trip and normalized comparison | Yes | tests.cache.test_store.TestStepCacheWorkingSet.test_save_serializes_step_text_from_addressing_text | INTEGRATION | Adequate, including representative failure paths |
+| Only successful load/save touches; skipped writes and misses do not | Yes | tests.cache.test_store.TestStepCacheWorkingSet.test_touch_marks_only_successful_load_and_save | CONTRACT | Adequate, including representative failure paths |
+| Unreadable metadata preserves file and warns | Yes | tests.cache.test_store.TestStepCacheWorkingSet.test_sweep_skips_unreadable_metadata_with_warning | INTEGRATION | Adequate, including representative failure paths |
+| Foreign and non-digest files survive; sweep idempotent | Yes | tests.cache.test_store.TestStepCacheWorkingSet.test_sweep_is_idempotent_and_repeat_close_safe | CONTRACT | Adequate, including representative failure paths |
+| Scope inspection/enumeration permission errors preserve files and warn | Yes | tests.cache.test_store.TestStepCacheWorkingSet.test_sweep_of_inaccessible_scope_returns_empty_with_warning[is_dir] | CONTRACT | Adequate, including representative failure paths |
+| Frozen PreparedStep, four fields and defaults | Yes | tests.engine.renderer.test_render.TestPreparedStepContract.test_declares_exactly_four_fields | CONTRACT | Adequate, including representative failure paths |
+| One snapshot, one evaluation, both outputs | Yes | tests.engine.renderer.test_render.TestAddressingRender.test_render_nondeterministic_filter_is_evaluated_once | CONTRACT | Adequate, including representative failure paths |
+| Capture source preservation and inactive branches | Yes | tests.engine.renderer.test_render.TestAddressingRender.test_render_preserves_reached_capture_tag_source | CONTRACT | Adequate, including representative failure paths |
+| Substituted Jinja text remains literal | Yes | tests.engine.renderer.test_render.TestAddressingRender.test_render_data_never_reparsed_in_addressing_text | CONTRACT | Adequate, including representative failure paths |
+| Marker collision raises loudly | Yes | tests.engine.renderer.test_render.TestAddressingRender.test_render_marker_collision_with_data_fails_loudly | CONTRACT | Adequate, including representative failure paths |
+| Comments, escaped quotes/backslashes do not shift source spans | Yes | tests.engine.renderer.test_render.TestAddressingRender.test_render_ignores_capture_syntax_in_comments_and_quoted_data[comment] | CONTRACT | Adequate, including representative failure paths |
+| Unterminated expressions, comments and raw blocks fail before execution | Yes | tests.engine.renderer.test_render.TestAddressingRender.test_render_malformed_scanner_boundaries_raise_authoring_error[{{ "unterminated] | CONTRACT | Adequate, including representative failure paths |
+| Snapshot isolation and atomic accepted publication | Yes | tests.engine.renderer.test_memory.TestStepMemoryContract.test_memory_is_importable_from_facade | CONTRACT | Adequate, including representative failure paths |
+| Exact result keys, string/nonblank values; no fabricated captures | Yes | tests.engine.renderer.test_validation.TestValidateStepResultContract.test_is_importable_from_facade | CONTRACT | Adequate, including representative failure paths |
+| Generation stores current addressing_text | Yes | tests.engine.test_generator.TestStepGeneratorLogic.test_generate_stores_addressing_text_of_prepared | INTEGRATION | Adequate, including representative failure paths |
+| Healing uses current render rather than old metadata | Yes | tests.engine.test_healer.TestStepHealerLogic.test_heal_retains_render_addressing_text_not_old_metadata | INTEGRATION | Adequate, including representative failure paths |
+| Fresh render identity and healing refresh; trace key retained | Yes | tests.engine.groups.test_recovery.TestGroupRecoveryRowReRender.test_row_identity_comes_from_fresh_render_addressing | INTEGRATION | Adequate, including representative failure paths |
+| Re-render sees earlier row publication and keeps caller traces unchanged | Yes | tests.engine.groups.test_recovery.TestGroupRecoveryRowReRender.test_recovery_rerenders_row_step_against_current_memory | INTEGRATION | Adequate, including representative failure paths |
+| Successful guided write-back preserves addressing text | Yes | tests.engine.steering.test_steering.TestStepSteeringLogic.test_write_back_carries_stuck_render_addressing_text | INTEGRATION | Adequate, including representative failure paths |
+| Executor evaluates each step once | Yes | tests.test_executor.TestStepExecutorRenderAndMemory.test_executor_renders_exactly_once_per_step_execution | INTEGRATION | Adequate, including representative failure paths |
+| Rendered values produce distinct caches and prevent cross-value replay | Yes | tests.test_integration.test_template_step_addresses_by_rendered_value_across_the_wired_cycle | INTEGRATION | Adequate, including representative failure paths |
+| Plain and equivalent template share one cache address | Yes | tests.test_integration.test_plain_sentence_and_identical_render_share_one_address_across_the_wired_cycle | INTEGRATION | Adequate, including representative failure paths |
+| Close preserves working set, removes own untouched files, cleanup=False preserves all | Yes | tests.test_integration.test_close_lifecycle_keeps_working_set_and_sweeps_untouched_entries | INTEGRATION | Adequate, including representative failure paths |
+| Teardown failure wins; unexpected sweep error is guarded | Yes | tests.test_scenario.TestCacheLifecycleOnClose.test_close_sweep_never_masks_teardown_and_never_raises | CONTRACT | Adequate, including representative failure paths |
+| Strict template replay validates and publishes without generation | Yes | tests.test_integration.test_strict_template_step_replay_validates_and_publishes_without_llm | INTEGRATION | Adequate, including representative failure paths |
+
+## Test Run Results
+1378 passed, 0 failed, 0 errors, 0 skipped, Python 3.12.15. Full suite with branch coverage completed in 9.06 seconds. Coverage: 2536/2546 statements (99.61%), 599/612 branches (97.88%), combined 99.27%. Ruff check passes; format check passes on 122 files.
+
+## Coverage Gaps
+| Coverage Point | Gap Type | Description |
+|---|---|---|
+| New renderer scanner boundaries | WARNING, RESOLVED | q2 approved automatic tests; 11 parameterized cases now pass |
+| Inaccessible sweep scope | CRITICAL behavior, RESOLVED | q1 approved repair; 2 parameterized error cases now pass |
+| Base VarExtension.parse | INFO | Six unexecuted lines belong to the non-facade base parser; render_step uses the overriding _MarkedVarExtension.parse. Runtime scanner branches are covered. |
+| Pre-existing internal branches | INFO | Residual branches include metadata ignoring an unrelated assignment, recovery occurrence matching and finite-delay checks; no uncovered changed public API was identified. |
+
+## Proposed Tests
+| Test | Type | File | Coverage Point Addressed | Priority |
+|---|---|---|---|---|
+| test_sweep_of_inaccessible_scope_returns_empty_with_warning | CONTRACT | tests/cache/test_store.py | is_dir/iterdir permission errors | CRITICAL — implemented |
+| test_render_ignores_capture_syntax_in_comments_and_quoted_data | CONTRACT | tests/engine/renderer/test_render.py | Comment/quote source span scanning | WARNING — implemented |
+| test_render_malformed_scanner_boundaries_raise_authoring_error | CONTRACT | tests/engine/renderer/test_render.py | Malformed scanner boundaries | WARNING — implemented |
+
+## Overall Coverage Assessment
+ADEQUATE. Changed APIs, storage lifecycle and cross-cell addressing are covered by contract and integration tests. Full suite passes; no open critical or warning coverage gaps. External provider/page boundaries are faked; this is not a live browser/provider smoke test.

prettyplay-0.0.3/.goga/history/2026/fix-step-cache/adr.md

@@ -0,0 +1,75 @@
+# Step cache addresses by the rendered sentence and cleans its scope on close
+
+---
+status: accepted
+date: 2026-10-11
+---
+
+The step cache addressed steps by their template source — "runtime values never enter the address" — so the same
+template rendered with different values replayed code generated for the wrong value, sometimes succeeding silently
+(the documented "accepted limitation" of the old addressing). We decided: the step address is now built from the
+**addressing text** — the rendered sentence with `{{ }}` substitutions applied (vars + memory), capture tags
+`{% var x %}` kept verbatim — and every `PrettyPlay` object, on `close()`, deletes the step files in its working
+scope whose addresses it did not load or save during its lifetime, governed by a new `cleanup` setting
+(`[tool.prettyplay] cleanup`, env `PRETTYPLAY_CLEANUP`, per-test override; default `True`).
+
+## Decision
+
+1. **Address structure unchanged, text changed**: the identity stays the triple
+   `(cache_key, step_type, normalize(addressing_text))` hashed with sha256 into the file name.
+2. **Addressing text**: a plain sentence addresses as itself; a template addresses by its render — `{{ }}`
+   substituted with actual values from vars and memory, `{% var x %}` capture tags remaining verbatim in the
+   addressing text. The LLM instruction keeps today's tag-stripped render — unchanged.
+   Keeping the capture tags makes templates differing only in capture names (`Read {% var a %}` vs
+   `Read {% var x %}`) address differently by construction.
+3. **One normalization for all addressing texts**: Unicode NFC + trim, verbatim — case and internal whitespace
+   are significant because rendered values are data ("Sign in" and "sign In" are different buttons). Casefold
+   and whitespace collapse are dropped from addressing; the old documented merge
+   («Click Sign in» == «click  sign in ») is gone by decision.
+4. **Cleanup flag**: a config field, layered like `strict`/`interactive` — pyproject, env, per-test override.
+   Default `True`: the cache is a per-test working set by default; persistence is opt-in (`cleanup = false`).
+5. **Cleanup algorithm on `close()`**: during execution the object accumulates the set of addresses it loaded
+   (cache hits, strict replays) or saved (generation, healing, steering/recovery write-backs, recovery
+   re-renders). On close it reads every step file in its working scope — the `cache_root` + `cache_path`
+   directory, filtered to files whose metadata carries this object's `cache_key` — and deletes the files whose
+   address is outside the touched set. Best-effort: a per-file failure never fails `close()` and is logged;
+   `close()` stays idempotent. Deletions are visible as log records; a hook event is a contract question for a
+   later stage.
+
+## Considered options
+
+- **Unified casefold normalization** (merge case/whitespace of the whole rendered text): rejected — it
+  reintroduces silent wrong hits for values differing only in case or spacing, the exact bug class this change
+  fixes; it did buy template/plain unification when texts coincide exactly, judged not worth it.
+- **Hybrid normalization** (plain sentences casefold, template renders verbatim): rejected — two addressing
+  regimes to document and explain; exact-text equality already unifies plain and rendered sentences without it.
+- **Capture declarations excluded from the address**: superseded by keeping `{% var %}` tags in the addressing
+  text — cheaper than a separate declarations component and collision-free.
+- **Cleanup scope = the whole `cache_path` directory regardless of `cache_key`**: rejected — with the default
+  shared root (`cache_path` unset) every test close would purge other tests' entries; the `cache_key` filter
+  (readable from file metadata) keeps the scope honest to "this object's working area".
+- **Cleanup default `False`**: rejected — the owner wants value-bearing cache entries treated as a per-test
+  working set unless persistence is explicitly requested.
+
+## Consequences
+
+- The committed-cache team workflow (generate locally, commit the directory, strict replay in CI) now requires
+  an explicit `cleanup = false`; with the default, generated entries vanish at test close. Strict replays keep
+  the entries they use (they load them), so a committed strict run is self-preserving.
+- Strict replay across processes requires the replay to render the exact same sentences as the generation run
+  (deterministic vars and application state).
+- Every existing cache file becomes unreachable (addresses change for plain and template steps alike): no
+  migration; docs say to purge the cache directory after upgrading — and the first `cleanup = True` close
+  sweeps the legacy files out of each test's scope as a side effect.
+- Attempt budgets keyed by `StepIdentity` follow the new addresses: the same template re-rendered against
+  changed memory is a different step with a fresh budget.
+- `ScenarioStep` records (raw sentence + prepared instruction) are unchanged.
+- Rendered values (vars, memory captures) now land in cache file metadata on disk — accepted knowingly;
+  see open questions.
+
+## Open questions
+
+- Security posture for value-bearing cache files (secrets in vars/captures reaching disk, logs and LLM
+  requests): deliberately deferred — no docs rule extended now, to be designed later.
+- Whether cache cleanup deserves a hook event (e.g. on_cache_deleted) alongside the log record — a contract
+  decision for the contract-designing stage, intentionally not fixed here.