docs: CEL context reference for control authors

[mlieberman85]

Summary

Closes #357. Adds docs/CEL_CONTEXT.md with a per-handler breakdown of what a control pass's expr can reference. Sourced from the actual handler evidence dicts and CELContext, not from stale notes in CLAUDE.md that were aimed at a different audience.

Why this doc exists

A control author writing expr = 'output.json.foo' gets no discoverable reference for what output.* contains -- they either grep other TOMLs or guess. Guessing produces silently-wrong CEL (e.g., referencing output.json on a pass that never set output_format = "json", or reaching for matches on a regex pass that no longer exposes it).

Content sourced from code, not CLAUDE.md

The old CLAUDE.md notes claimed:

• pattern: files, matches -- but matches is not in the current regex_handler's evidence.
• api: response.status_code, response.body, response.headers -- but there is no verification api handler; api_call is a remediation handler with no expr evaluator.

The new doc covers what the current implementation actually exposes and calls out which handlers do NOT evaluate expr today so authors don't silently write a no-op.

What landed

• docs/CEL_CONTEXT.md (new, +212 lines): per-handler variable tables (exec, file_exists, regex/pattern, mcp), ambient bindings (project, repo, context), the two custom functions with signatures + failure modes, common patterns, and an error-behavior note.
• docs/HANDLER_AUTHORING.md: replaced the old inline variable enumeration with an accurate one-line summary + a link to the new reference.
• docs/architecture/framework-design.md: added a link to the reference on the expr field row.

Non-goals

• Not modifying any handler code -- pure docs.
• Not proposing new context variables. Adding one is a CELContext change (spec-implementation sync gate applies) and belongs in a separate PR.
• No mention of a hypothetical api verification handler or a matches array on regex; if those land later, add them here.

Closes #357.

[Marc-cn]

Checked the tables against the handler evidence dicts, exec, file_exists and mcp all match. Two things before merge:

1. "Bindings available regardless of handler" doesn't hold on the post-step path. orchestrator.py:130 builds cel_context = {"output": handler_result.evidence or {}} only output is bound, and nothing constructs a CELContext for_apply_cel_expr. Running the doc's own example against that context:

'project.language == "python"' success=False undeclared reference to 'project'
'repo.owner == "x"' success=False undeclared reference to 'repo'
'output.exit_code == 0' success=True value=True

And per _apply_cel_expr the failure just logs a warning and preserves the handler verdict, so an author gets no signal. Worth scoping that section to "not available in post-step expr" or dropping it.

2. files_found / found_files come from the exclude-globs branch (builtin_handlers.py:400-404), not the regex/pattern match path the table describes. A regex pass that matched files exposes files_checked; a pass thatresolved nothing exposes files_checked only (line 502)

rest lgtm