From fb151da6dab26dbb3c5ba7fdb739e4dc06174070 Mon Sep 17 00:00:00 2001 From: tn-pisama Date: Thu, 10 Sep 2026 09:54:33 -0700 Subject: [PATCH] docs: clarify observe-only healing result semantics --- README.md | 13 ++++ docs/plans/healing-result-documentation.md | 71 ++++++++++++++++++++++ src/pisama/agents/heal.py | 11 +++- 3 files changed, 93 insertions(+), 2 deletions(-) create mode 100644 docs/plans/healing-result-documentation.md diff --git a/README.md b/README.md index f125593..1375d82 100644 --- a/README.md +++ b/README.md @@ -237,6 +237,19 @@ This used to require the standalone `pisama-agent-sdk` package. That package still works and stays fully supported for existing installs; `pisama[agents]` is the recommended path for new projects, one package instead of two. +### Interpreting synchronous healing results + +When `pisama.agents.heal.heal_now` returns `applied=False` and `escalated=False`, +remain observe-only. This does not necessarily mean "no suggestion." The response may +retain `fix` and a derived `prompt_patch` for human inspection when calibration +evidence is unavailable. Do not apply a suggestion just because it is present; +neither flag asserts that it was escalated for approval. + +The current parser does not expose unknown response fields such as +`application_blocked_reason`. It preserves recognized fields including +`applied`, `escalated`, `message`, and `fix`. This compatibility is not a +certification of autonomous safety if detector evidence is restored later. + ## Detectors Core detectors, gated per platform (n8n, LangGraph, Dify, OpenClaw and others). A representative selection: diff --git a/docs/plans/healing-result-documentation.md b/docs/plans/healing-result-documentation.md new file mode 100644 index 0000000..ac48197 --- /dev/null +++ b/docs/plans/healing-result-documentation.md @@ -0,0 +1,71 @@ +# Healing result documentation + +**Status:** In review +**As of:** 2026-09-10 +**Owner:** engineering +**Supersedes:** none +**Evidence scope:** branch-only documentation + +## Goal and boundaries + +Starting from canonical main adc070a40e4e866308f876e6e69aa493d6abd4c9, clarify that both application and +escalation flags being false does not imply an absent suggestion. Callers must +remain observe-only; a retained fix or derived patch is for human inspection, +not permission to apply it. Document the current parser's omission of unknown +response fields without implying loss of its recognized flags and message. + +Only README, Python docstrings, and this plan may change. No behavior, +dependencies, versions, generated packages, publication, provider calls, or +production writes. This is not certification of autonomous safety if evidence +is restored later. No repository AGENTS.md or CLAUDE.md exists at this base; +CONTRIBUTING.md was read. + +## Verification / DONE + +- Inspect src/pisama/agents/heal.py and the canonical Python parser. +- Compare Python AST with base after removing docstrings: executable code must + be identical; confirm dependency/version manifests unchanged. +- Run the existing real-object, network-free tests/agents/test_heal.py controls. +- Check documentation wording and git diff --check. +- Independent root review is required before any push. No documentation build + configuration exists in this repository; package builds are separate checks. + +## State + +Plan recorded before documentation edits. README and Python docstrings now +clarify observe-only behavior, inspection-only suggestions, and the parser's +recognized-field boundary. Executable AST comparison against the starting +commit (after removing docstrings) passed; pyproject.toml is unchanged. + +Actual focused command: + +```bash +PYTHONPATH=src /Users/tuomonikulainen/pisama/backend/.venv/bin/python -m pytest --noconftest tests/agents/test_heal.py -q +git diff --check +``` + +Four real-object tests passed in 0.23s, zero skips. These exercise existing +accessors, not live hosted endpoint behavior or published artifact delivery. +The Agent SDK is a thin forwarder: its current canonical source has no +independent result parser or duplicated HealingResult class. The Python +canonical parser contains the obsolete both-false wording; the shim README +and module now explain the forwarded semantics. + +Full contributor checks on Python 3.11.13 with public pisama-core 1.11.0: +250 tests passed in 19.27s, zero skips; coverage 71.74% exceeds the existing +60% gate. Ruff passed; mypy passed all 66 source files. Initial CONTRIBUTING +install of dev,mcp lacked opentelemetry for collection; installing the existing +auto extra, as CI already does, resolved this without source/dependency edits. +Fresh local wheel and sdist builds and twine checks passed, followed by clean +wheel installation and CLI help. Outputs are local verification artifacts only, +not a new 0.7.0 release or permission to overwrite public packages. +No multi-Python CI matrix or CI-pinned core 1.8.2 run is claimed. + +Full tests ran with an empty inherited credential environment and an audit +hook rejecting non-loopback socket connections in the pytest process. +Existing suite internals were not rewritten and are not being presented as +live-provider workflow proof. + +Root approved the documentation-only diff; the requested grammar correction +was applied. No runtime code, version, dependency, push, package publication, +or production change. Commits remain isolated for root release review. diff --git a/src/pisama/agents/heal.py b/src/pisama/agents/heal.py index f35a5df..304cac9 100644 --- a/src/pisama/agents/heal.py +++ b/src/pisama/agents/heal.py @@ -49,8 +49,15 @@ class HealingResult: verification, see D7) was returned and is ready to apply inline. `escalated`: no fix passed the inline gates; the top fix requires human approval. - Both false means no fix was available at all (e.g. unrecognised - detection type) — caller should fall back to its observe-only path. + Both false means inline application is not authorized; caller must + remain observe-only. A fix payload or derived prompt_patch may still + be present for human inspection, including when calibration evidence + is unavailable. Its presence is not permission to apply it. + + Unknown response fields, such as application_blocked_reason, are not + exposed by this parser. Recognized flags, message, and fix are retained. + These result semantics do not certify autonomous safety if detector + evidence becomes available again. `verification_passed` is populated when the server ran inline verification (MEDIUM-tier fixes only): True iff the simulated apply