@crown-dev-studios/review-council 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,158 @@
1
+ # Output Contract
2
+
3
+ `review-council` groups run attempts by review session:
4
+
5
+ ```text
6
+ docs/reviews/<review-id>/
7
+ latest-run.json
8
+ runs/
9
+ <run-id>/
10
+ run.json
11
+ bundle.json
12
+ index.html
13
+ claude/
14
+ report.md
15
+ findings.json
16
+ done.json
17
+ status.json
18
+ stdout.log
19
+ stderr.log
20
+ codex/
21
+ report.md
22
+ findings.json
23
+ done.json
24
+ status.json
25
+ stdout.log
26
+ stderr.log
27
+ judge/
28
+ summary.md
29
+ verdict.json
30
+ done.json
31
+ status.json
32
+ stdout.log
33
+ stderr.log
34
+ ```
35
+
36
+ ## Reviewer Output
37
+
38
+ Each reviewer writes:
39
+
40
+ - `report.md`: human-readable review
41
+ - `findings.json`: structured findings matching `schemas/review-findings.schema.json`
42
+ - `done.json`: sentinel file confirming the agent finished writing artifacts
43
+
44
+ `done.json` shape:
45
+
46
+ ```json
47
+ {
48
+ "review_id": "staged-changes-review",
49
+ "run_id": "20260318-143000123-abc12345",
50
+ "reviewer": "claude",
51
+ "status": "complete",
52
+ "completed_at": "2026-03-07T18:30:00Z",
53
+ "finding_count": 4
54
+ }
55
+ ```
56
+
57
+ ## Judge Output
58
+
59
+ The judge writes:
60
+
61
+ - `summary.md`: final markdown summary for humans
62
+ - `verdict.json`: adjudicated findings matching `schemas/judge-verdict.schema.json`
63
+ - `done.json`: sentinel confirming the judge finished
64
+
65
+ ## Stage Status
66
+
67
+ The orchestrator writes `status.json` per stage with these fields:
68
+
69
+ ```json
70
+ {
71
+ "review_id": "staged-changes-review",
72
+ "run_id": "20260318-143000123-abc12345",
73
+ "stage": "claude",
74
+ "command": "claude -p ...",
75
+ "started_at": "2026-03-07T18:25:00Z",
76
+ "finished_at": "2026-03-07T18:30:00Z",
77
+ "exit_code": 0,
78
+ "require_sentinel": true,
79
+ "done_file_present": true,
80
+ "required_artifacts": ["report.md", "findings.json", "done.json"],
81
+ "artifact_presence": { "report.md": true, "findings.json": true, "done.json": true },
82
+ "missing_artifacts": [],
83
+ "success": true,
84
+ "failure_reason": null,
85
+ "timed_out": false,
86
+ "attempts": 1,
87
+ "retried": false,
88
+ "stdout_log": "/path/to/stdout.log",
89
+ "stderr_log": "/path/to/stderr.log"
90
+ }
91
+ ```
92
+
93
+ On validation failure or missing artifacts, `status.json` additionally contains:
94
+
95
+ ```json
96
+ {
97
+ "success": false,
98
+ "failure_reason": "schema_validation_failed",
99
+ "validation_errors": [
100
+ { "path": "findings[0].severity", "message": "value \"critical\" not in enum [\"p1\", \"p2\", \"p3\"]" }
101
+ ]
102
+ }
103
+ ```
104
+
105
+ Key fields:
106
+
107
+ | Field | Type | Description |
108
+ |---|---|---|
109
+ | `exit_code` | number | Process exit code. `124` on timeout. |
110
+ | `timed_out` | boolean | Whether the stage was killed due to timeout. |
111
+ | `attempts` | number | Total attempts (1 = no retries). |
112
+ | `retried` | boolean | Whether the stage was retried at least once. |
113
+ | `missing_artifacts` | array | Required artifacts still missing after the final attempt. |
114
+ | `failure_reason` | string? | `process_failed`, `timeout`, `missing_artifacts`, or `schema_validation_failed`. |
115
+ | `validation_errors` | array? | Schema validation errors if the output JSON was malformed. |
116
+
117
+ ## Bundle Output
118
+
119
+ The HTML renderer writes:
120
+
121
+ - `bundle.json`: packages statuses, raw findings, raw reports, judge output, and artifact status into a single file
122
+ - `index.html`: static page for side-by-side reading
123
+
124
+ `bundle.json` shape:
125
+
126
+ ```json
127
+ {
128
+ "review_id": "staged-changes-review",
129
+ "run_id": "20260318-143000123-abc12345",
130
+ "review_target": "staged changes",
131
+ "run": { "review_id": "...", "run_id": "...", "review_target": "...", "created_at": "..." },
132
+ "candidate_findings": [ { "reviewer": "claude", "severity": "p1", "title": "...", "confidence": "high", "files": [] } ],
133
+ "judge_verdict": { "overall_verdict": "needs-fixes", "..." : "..." },
134
+ "status": {
135
+ "claude": { "success": true, "..." : "..." },
136
+ "codex": { "success": true, "..." : "..." },
137
+ "judge": { "success": true, "..." : "..." }
138
+ },
139
+ "reports": {
140
+ "claude": "markdown...",
141
+ "codex": "markdown...",
142
+ "judge": "markdown..."
143
+ },
144
+ "artifact_status": {
145
+ "claude": "ok",
146
+ "codex": "ok",
147
+ "judge": "ok"
148
+ }
149
+ }
150
+ ```
151
+
152
+ `artifact_status` values: `"ok"` (valid JSON loaded), `"missing"` (file not found), `"malformed"` (file exists but is not valid JSON).
153
+
154
+ ## Ownership Rules
155
+
156
+ - Reviewer outputs are candidate findings, not authoritative todos
157
+ - The judge owns the final verdict
158
+ - Todo creation should be a follow-up step from `verdict.json`, not from raw reviewer output
@@ -0,0 +1,48 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "title": "Review Council Judge Done Sentinel",
4
+ "type": "object",
5
+ "required": [
6
+ "review_id",
7
+ "run_id",
8
+ "reviewer",
9
+ "status",
10
+ "completed_at",
11
+ "confirmed_count",
12
+ "contested_count",
13
+ "rejected_count"
14
+ ],
15
+ "properties": {
16
+ "review_id": {
17
+ "type": "string"
18
+ },
19
+ "run_id": {
20
+ "type": "string"
21
+ },
22
+ "reviewer": {
23
+ "type": "string",
24
+ "const": "judge"
25
+ },
26
+ "status": {
27
+ "type": "string",
28
+ "const": "complete"
29
+ },
30
+ "completed_at": {
31
+ "type": "string",
32
+ "format": "date-time"
33
+ },
34
+ "confirmed_count": {
35
+ "type": "integer",
36
+ "minimum": 0
37
+ },
38
+ "contested_count": {
39
+ "type": "integer",
40
+ "minimum": 0
41
+ },
42
+ "rejected_count": {
43
+ "type": "integer",
44
+ "minimum": 0
45
+ }
46
+ },
47
+ "additionalProperties": false
48
+ }
@@ -0,0 +1,132 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "title": "Review Council Judge Verdict",
4
+ "type": "object",
5
+ "required": [
6
+ "review_id",
7
+ "run_id",
8
+ "target",
9
+ "generated_at",
10
+ "overall_verdict",
11
+ "summary_markdown",
12
+ "confirmed_findings",
13
+ "contested_findings",
14
+ "rejected_findings",
15
+ "todo_recommendations"
16
+ ],
17
+ "properties": {
18
+ "review_id": {
19
+ "type": "string"
20
+ },
21
+ "run_id": {
22
+ "type": "string"
23
+ },
24
+ "target": {
25
+ "type": "string"
26
+ },
27
+ "generated_at": {
28
+ "type": "string",
29
+ "format": "date-time"
30
+ },
31
+ "overall_verdict": {
32
+ "type": "string",
33
+ "enum": [
34
+ "approve",
35
+ "needs-fixes",
36
+ "blocked",
37
+ "incomplete"
38
+ ]
39
+ },
40
+ "summary_markdown": {
41
+ "type": "string"
42
+ },
43
+ "confirmed_findings": {
44
+ "type": "array",
45
+ "items": {
46
+ "$ref": "#/$defs/verdictFinding"
47
+ }
48
+ },
49
+ "contested_findings": {
50
+ "type": "array",
51
+ "items": {
52
+ "$ref": "#/$defs/verdictFinding"
53
+ }
54
+ },
55
+ "rejected_findings": {
56
+ "type": "array",
57
+ "items": {
58
+ "$ref": "#/$defs/verdictFinding"
59
+ }
60
+ },
61
+ "todo_recommendations": {
62
+ "type": "array",
63
+ "items": {
64
+ "type": "object",
65
+ "required": [
66
+ "title",
67
+ "priority",
68
+ "reason"
69
+ ],
70
+ "properties": {
71
+ "title": {
72
+ "type": "string"
73
+ },
74
+ "priority": {
75
+ "type": "string",
76
+ "enum": [
77
+ "p1",
78
+ "p2",
79
+ "p3"
80
+ ]
81
+ },
82
+ "reason": {
83
+ "type": "string"
84
+ }
85
+ },
86
+ "additionalProperties": false
87
+ }
88
+ }
89
+ },
90
+ "$defs": {
91
+ "verdictFinding": {
92
+ "type": "object",
93
+ "required": [
94
+ "title",
95
+ "status",
96
+ "reason"
97
+ ],
98
+ "properties": {
99
+ "title": {
100
+ "type": "string"
101
+ },
102
+ "status": {
103
+ "type": "string",
104
+ "enum": [
105
+ "confirmed",
106
+ "contested",
107
+ "rejected"
108
+ ]
109
+ },
110
+ "reason": {
111
+ "type": "string"
112
+ },
113
+ "reviewer_ids": {
114
+ "type": "array",
115
+ "items": {
116
+ "type": "string"
117
+ }
118
+ },
119
+ "final_priority": {
120
+ "type": "string",
121
+ "enum": [
122
+ "p1",
123
+ "p2",
124
+ "p3"
125
+ ]
126
+ }
127
+ },
128
+ "additionalProperties": false
129
+ }
130
+ },
131
+ "additionalProperties": false
132
+ }
@@ -0,0 +1,42 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "title": "Review Council Reviewer Done Sentinel",
4
+ "type": "object",
5
+ "required": [
6
+ "review_id",
7
+ "run_id",
8
+ "reviewer",
9
+ "status",
10
+ "completed_at",
11
+ "finding_count"
12
+ ],
13
+ "properties": {
14
+ "review_id": {
15
+ "type": "string"
16
+ },
17
+ "run_id": {
18
+ "type": "string"
19
+ },
20
+ "reviewer": {
21
+ "type": "string",
22
+ "enum": [
23
+ "claude",
24
+ "codex",
25
+ "other"
26
+ ]
27
+ },
28
+ "status": {
29
+ "type": "string",
30
+ "const": "complete"
31
+ },
32
+ "completed_at": {
33
+ "type": "string",
34
+ "format": "date-time"
35
+ },
36
+ "finding_count": {
37
+ "type": "integer",
38
+ "minimum": 0
39
+ }
40
+ },
41
+ "additionalProperties": false
42
+ }
@@ -0,0 +1,114 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "title": "Review Findings Export",
4
+ "type": "object",
5
+ "required": [
6
+ "review_id",
7
+ "run_id",
8
+ "reviewer",
9
+ "target",
10
+ "generated_at",
11
+ "summary",
12
+ "findings"
13
+ ],
14
+ "properties": {
15
+ "review_id": {
16
+ "type": "string"
17
+ },
18
+ "run_id": {
19
+ "type": "string"
20
+ },
21
+ "reviewer": {
22
+ "type": "string",
23
+ "enum": [
24
+ "claude",
25
+ "codex",
26
+ "other"
27
+ ]
28
+ },
29
+ "target": {
30
+ "type": "string"
31
+ },
32
+ "generated_at": {
33
+ "type": "string",
34
+ "format": "date-time"
35
+ },
36
+ "summary": {
37
+ "type": "string"
38
+ },
39
+ "findings": {
40
+ "type": "array",
41
+ "items": {
42
+ "type": "object",
43
+ "required": [
44
+ "id",
45
+ "title",
46
+ "severity",
47
+ "confidence",
48
+ "category",
49
+ "description",
50
+ "evidence",
51
+ "recommended_fix",
52
+ "files"
53
+ ],
54
+ "properties": {
55
+ "id": {
56
+ "type": "string"
57
+ },
58
+ "title": {
59
+ "type": "string"
60
+ },
61
+ "severity": {
62
+ "type": "string",
63
+ "enum": [
64
+ "p1",
65
+ "p2",
66
+ "p3"
67
+ ]
68
+ },
69
+ "confidence": {
70
+ "type": "string",
71
+ "enum": [
72
+ "high",
73
+ "medium",
74
+ "low"
75
+ ]
76
+ },
77
+ "category": {
78
+ "type": "string"
79
+ },
80
+ "description": {
81
+ "type": "string"
82
+ },
83
+ "evidence": {
84
+ "type": "string"
85
+ },
86
+ "recommended_fix": {
87
+ "type": "string"
88
+ },
89
+ "files": {
90
+ "type": "array",
91
+ "items": {
92
+ "type": "object",
93
+ "required": [
94
+ "path"
95
+ ],
96
+ "properties": {
97
+ "path": {
98
+ "type": "string"
99
+ },
100
+ "line": {
101
+ "type": "integer",
102
+ "minimum": 1
103
+ }
104
+ },
105
+ "additionalProperties": false
106
+ }
107
+ }
108
+ },
109
+ "additionalProperties": false
110
+ }
111
+ }
112
+ },
113
+ "additionalProperties": false
114
+ }
@@ -0,0 +1,51 @@
1
+ # Review Council Judge
2
+
3
+ You are the adjudication pass for Review Council.
4
+
5
+ ## Inputs
6
+
7
+ - Review ID: `{{REVIEW_ID}}`
8
+ - Run ID: `{{RUN_ID}}`
9
+ - Run directory: `{{RUN_DIR}}`
10
+ - Review target: `{{TARGET}}`
11
+ - Claude report: `{{RUN_DIR}}/claude/report.md`
12
+ - Claude findings: `{{RUN_DIR}}/claude/findings.json`
13
+ - Codex report: `{{RUN_DIR}}/codex/report.md`
14
+ - Codex findings: `{{RUN_DIR}}/codex/findings.json`
15
+
16
+ If a listed reviewer directory does not exist in this run, that reviewer did not run. Ignore missing reviewer files and adjudicate only the artifacts that are present.
17
+
18
+ ## Required Outputs
19
+
20
+ 1. Write the final markdown summary to:
21
+ `{{ARTIFACT_DIR}}/summary.md`
22
+ 2. Write structured verdict JSON matching:
23
+ `{{SCHEMA_PATH}}`
24
+ to:
25
+ `{{ARTIFACT_DIR}}/verdict.json`
26
+ 3. Write a completion sentinel to:
27
+ `{{ARTIFACT_DIR}}/done.json`
28
+
29
+ ## Judge Rules
30
+
31
+ - Confirm findings that are well-supported by evidence in the diff or both reviewers
32
+ - Mark findings as contested if one reviewer makes a plausible claim that still needs human verification
33
+ - Reject findings that are weak, duplicated, or unsupported
34
+ - Recommend final todos only for confirmed or high-signal contested findings
35
+ - Do not create files in `todos/`
36
+ - Preserve `review_id: "{{REVIEW_ID}}"` and `run_id: "{{RUN_ID}}"` in every JSON artifact you write
37
+
38
+ ## done.json Shape
39
+
40
+ ```json
41
+ {
42
+ "review_id": "{{REVIEW_ID}}",
43
+ "run_id": "{{RUN_ID}}",
44
+ "reviewer": "judge",
45
+ "status": "complete",
46
+ "completed_at": "ISO-8601",
47
+ "confirmed_count": 0,
48
+ "contested_count": 0,
49
+ "rejected_count": 0
50
+ }
51
+ ```