diff --git a/docs/superpowers/specs/2026-06-11-guardian-goal-authorization-design.md b/docs/superpowers/specs/2026-06-11-guardian-goal-authorization-design.md new file mode 100644 index 0000000000..12bc42b1da --- /dev/null +++ b/docs/superpowers/specs/2026-06-11-guardian-goal-authorization-design.md @@ -0,0 +1,77 @@ +# Guardian Goal Authorization Evidence + +## Problem + +Guardian's approval policy already treats a necessary implementation of an explicitly requested operation as strong user-authorization evidence. However, Guardian's transcript builder drops all contextual user messages. Persisted goal continuations are contextual messages, so Guardian does not see a user-provided goal even when the goal explicitly names the action under review. + +In CODEX-21G8, the active goal required rebuilding `Shadow-0.4.dmg` and updating GitHub release `v0.4.0` with the new binary. Guardian did not receive that objective and repeatedly classified the upload as `user_authorization = "unknown"`. After the user repeated authorization in an ordinary chat message, Guardian classified the same upload as `high` authorization and allowed it. + +## Goals + +- Preserve a persisted goal's user-provided objective as authorization evidence in Guardian review. +- Keep unrelated contextual scaffolding out of the Guardian transcript. +- Avoid weakening Guardian's existing risk or authorization thresholds. +- Avoid repeatedly sending an unchanged objective on every automatic continuation. + +## Non-goals + +- Automatically approve every action that advances a goal. +- Treat model-authored plans, tool output, or assistant statements as user authorization. +- Change tenant policy for public release publication or other high-risk actions. +- Include full goal-continuation instructions in Guardian context. + +## Design + +Extend contextual-fragment parsing with a narrow parser for canonical internal context envelopes. In Guardian transcript collection, recognize only internal context whose trusted source label is `goal`, then extract only the contents of `` or ``. + +Represent the extracted text as a distinct `UserGoal` transcript entry rendered as `user-provided goal`. Treat this entry like a user entry for transcript-retention priority, but keep its distinct label so the reviewer can distinguish a persisted objective from a fresh chat message. + +Track the most recently retained goal objective while walking history. Skip consecutive repetitions of the same objective and append a new entry when the objective changes. This preserves initial creation and later user edits without filling the transcript with automatic-continuation duplicates. + +Do not change `policy_template.md` initially. Its existing definition of `high` authorization already covers necessary implementations of explicitly requested operations. The defect is missing evidence, not an insufficient threshold rule. + +## Data Flow + +1. The goal extension injects `` into parent history. +2. Guardian transcript collection recognizes that canonical envelope before applying the generic contextual-message exclusion. +3. The collector extracts the objective and emits a `UserGoal` entry. +4. Guardian receives the labeled objective alongside the exact proposed action. +5. Guardian applies the existing risk and authorization policy. + +## Security and Failure Handling + +- Accept only a well-formed canonical internal-context envelope with source exactly `goal`. +- Extract only the objective element; discard continuation rules, budgets, and other runtime instructions. +- Treat the objective as untrusted evidence, consistent with the rest of the Guardian transcript. +- If parsing fails or the objective is empty, omit it rather than forwarding the full contextual message. +- Preserve current behavior for environment, skill, extension, and other contextual messages. +- A goal is evidence of requested outcome, not blanket authorization. Guardian must still compare the proposed target and side effects with the objective under its existing policy. + +## Testing + +Add focused unit coverage for transcript collection and prompt construction: + +- Ordinary contextual messages remain excluded. +- A canonical goal continuation contributes only the objective. +- An edited goal using `` contributes the updated objective. +- Repeated identical continuations produce one retained objective entry. +- A changed objective produces a later distinct entry. +- Malformed, empty, non-goal, and unrelated contextual messages remain excluded. +- A full Guardian prompt for `gh release upload v0.4.0 Shadow-0.4.dmg` includes the matching user-provided release objective and the planned action. +- An unrelated action fixture demonstrates that the objective and action remain separately labeled; no deterministic code path pre-classifies it as authorized. + +Run the targeted `codex-core` Guardian tests, then formatting and the repository's normal focused checks for the touched crates. Add or run a model-level replay/eval separately to verify that the matching release-upload case produces high authorization while an unrelated upload remains low or unknown. + +## Files Expected to Change + +- `codex-rs/core/src/context/internal_model_context.rs`: expose narrow parsing/access for canonical internal context. +- `codex-rs/core/src/context/mod.rs`: export the parser or parsed fragment access needed by Guardian. +- `codex-rs/core/src/guardian/prompt.rs`: extract, deduplicate, label, and retain goal objectives. +- `codex-rs/core/src/guardian/tests.rs`: unit and prompt-level regression coverage. + +## Success Criteria + +- CODEX-21G8's goal objective would be visible in the approval-review prompt before the release upload decision. +- Existing contextual-message filtering remains intact. +- No risk threshold or automatic allow path is added. +- Targeted tests pass and snapshots, if affected, are intentionally updated.