feat(diff): name the changed declarations in an OpenShell policy row (#968)

[pengfei-threemoonslab]

What

For openshift-kni/ai-sandbox#29 the human OpenShell row printed authored, OpenShell 0.1.2, 6 endpoint(s), facts <digest> -> …7 endpoint(s), facts <digest> plus correct limits, but not which read path narrowed, which binary selectors changed or which destinations were added. The row now names them. Presentation only.

Before:

unknown changed openshell rds-policy/evals/openshell-policy.yaml
  authored, OpenShell 0.1.2, 6 endpoint(s), facts <digest> → authored, OpenShell 0.1.2, 7 endpoint(s), facts <digest>
  narrows filesystem read paths; wildcard or unresolved executable selector is outside exact comparison; a single authority direction is unknown; declared policy only; ...

After (same fixture shape; the reason line is unchanged):

unknown changed openshell rds-policy/evals/openshell-policy.yaml
  authored, OpenShell 0.1.2: filesystem read_only -/sandbox/.uv/python; destination aiplatform.googleapis.com:443 (l4) binaries +/tmp/**/node_modules/@anthropic-ai/claude-agent-sdk-linux-x64/claude -/usr/local/bin/claude; destinations files.pythonhosted.org:443, pypi.org:443 (l4) binaries +/tmp/.local/bin/uv +/usr/bin/python3* -/usr/local/bin/uv; destination github.com:443 (l4) binaries +/tmp/.local/bin/uv; removed destination oauth2.googleapis.com:443 (l4) via /usr/local/bin/claude; added destinations objects.githubusercontent.com:443, release-assets.githubusercontent.com:443 (l4) via /tmp/.local/bin/uv, /usr/bin/git, /usr/lib/git-core/**
  narrows filesystem read paths; wildcard or unresolved executable selector is outside exact comparison; a single authority direction is unknown; declared policy only; ...

Design

• The established per-row "field difference" slot (_RowView.change, published as review.changes[].change, already used for hooks and MCP servers) carries the text. Every consumer reads it through review_changes: diff text and --json, verify host comparison, check, and the PR comment (including its bounded/shortened form).
• New core/openshell_row_detail.py reads the normalized facts.policy the comparator reads. It names filesystem paths added/removed per list, include_workdir, Landlock compatibility, process identity, and per destination the binary selectors added/removed plus destination/request declarations (protocol, enforcement, access preset, allow/deny method and path) added, removed or edited. Destinations that changed alike share one entry. Lists are bounded (5 paths or selectors, 8 destination entries, 3 selectors per added/removed destination), then and N more.
• Redaction: only inventory-published values. Each printed value is re-run through the inventory's _openshell_public_value sanitizer and replaced with <redacted> on any change (defence in depth; the reader already refuses a document whose values would change). Query/param constraints and endpoint options appear by field name, never value; rule names and comments are never printed. An option value change reads other options changed (not shown); a change in no named field says so.
• A newly selected or removed document keeps its counts and digest and appends declared: … with filesystem lists, Landlock/process (with omitted = default named), destinations with selectors, and the number of inspected endpoints that default to audit enforcement. It is a description, not a proof of expansion.
• Unchanged: rows[] values, direction, expands, severity, expansion signals, check decisions, limit wording. No schema, contract or version change; no schema file touched.

Tests

tests/test_openshell_row_detail.py (21 tests): the issue-shaped static fixture on diff text/JSON, verify/--preview JSON and the PR comment (whole and tight); direction/expands/limits unchanged; controls for unchanged policy (no row), equivalent respelling (no row), option-value-only change, composition-only change (existing limit wording), many paths/destinations/selectors (bounded), request declarations without query values, preset/enforcement transition, secret-shaped path/host (withheld; reader refuses the document), added and removed documents.

Full CI mirror: 16527 passed, 4 failed (the two known local_settings_enabled_plugins-* machine failures; two test_workflow_label_redaction linear-time wall-clock tests that pass when rerun alone). tests/test_adapter_static_only.py passes. ruff check . clean.

Closes #968

🤖 Generated with Claude Code