Use validated JSON for review and triage data

[taspinar]

What changed

• Schemas: .agents/schemas/review.schema.json and triage.schema.json define the result an agent must return.
• Shared library: scripts/lib/review-data.sh validates agent results and stored artifacts with the same rules and renders the Markdown reports. The launcher passes the schema to the provider (codex exec --output-schema, claude --json-schema).
• Two files per review and triage: .json is the source of truth; .md is generated for reading and never parsed.
• Rules beyond the schema: exactly one JSON value, no unexpected or missing fields, non-empty finding fields, and a verdict that follows from the findings. Triage decides every finding exactly once, Critical and Major are FIX_NOW, and a deferred finding has a complete follow-up.
• Script-owned data: the script numbers the findings (C1, M1, MIN1, S1) and builds stored artifacts from allowed fields only.
• Retry: invalid agent output is retried once, then rejected before anything is stored or created.
• Triage: the approval preview shows the full follow-up proposal. A triage is complete only when every deferred finding has its follow-up Issue; an incomplete artifact is rejected by apply-triage.sh, and a new triage round reuses Issues already created.
• Interface change: triage-review.sh and apply-triage.sh take the .json artifact.
• The duplicated AWK finding parsers are removed. The review, triage, and apply-triage tests now run in isolated temporary repositories, which removed the nested-verification guard.
• Contracts and documentation are updated.

Issue / acceptance criteria

Closes #37

Risk

• Low
• Medium
• High

Verification evidence

• ./scripts/verify.sh passed (9 checks)
• Tests added/updated where appropriate (suites also pass under macOS system bash 3.2)
• Independent review completed when required
• Architecture/docs/ADR updated when required

Exercised against a real Codex session (gpt-6-astra): review with schema, storage and rendering, and triage with schema up to the approval question (declined, so no Issues were created).

Independent review, two rounds with Codex through review-feature.sh:

• Round 1, CHANGES REQUIRED: agent output could override script-owned fields; stored artifacts bypassed the content rules; multiple JSON values were accepted as one result. All fixed, with rejection tests.
• Round 2, CHANGES REQUIRED: an artifact left incomplete by a failed Issue creation was accepted as approved (Major); an absent followup field was accepted (Minor); the approval preview omitted the follow-up action and criteria (Minor). All fixed, with tests. Not reviewed again after these fixes.

Not verified: the Claude side of structured output. The claude CLI on this machine is not authenticated, so how Claude returns the structured result (structured_output in the JSON envelope) is assumed and covered with fake agents only.

Update: real Claude run and agent isolation

After the Claude CLI was logged in, the Claude path was exercised for real: review and triage with schema, through structured_output as assumed.

• Claude review (fable), CHANGES REQUIRED with 9 findings. All addressed: tests for every validation rule; jq found by the tests wherever it is installed; triage stored only after every follow-up Issue exists; script-owned fields constrained (finding ids such as ../S1, positive integer Issue and round, copied review data); Claude's real exit status returned and the structured-output path tested; isolation of read-only sessions (below); a pre-JSON review is no longer a re-review input; the retry tells the agent why its result was rejected; consistent argument order and deterministic test names.
• Read-only isolation. Probes against the real CLIs showed that both read-only sessions received MCP servers, apps, and remote tools from the user's configuration (Claude: document create/update/delete; Codex: site deployment, environment variables, parental controls, and more). Claude now runs with --restricted --strict-mcp-config --permission-mode dontAsk --tools Read,Glob,Grep. Codex now runs with --ignore-user-config and apps, browser use, computer use, and web search disabled. Both were re-probed: they read files, cannot write, and get no MCP tools.
• Codex review through the isolated profile: PASS WITH MINOR FINDINGS. MIN1 (follow-up Issue references and triage metadata not fully validated) fixed, with tests.

Agent involvement

Planner: —
Implementer: Claude (Opus 5.5)
Reviewer: Codex (gpt-6-astra)

Production impact

None.

🤖 Generated with Claude Code