@onlooker-community/ecosystem 0.10.0 → 0.15.0

package/plugins/tribunal/scripts/lib/tribunal-gate.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# Gate decision for Tribunal.
+#
+# Resolves a gate verdict (passed | blocked + reason) from the four schema
+# gate_policy values: strict, majority, unanimous, meta_override.
+#
+# Each policy operates over:
+#   - verdicts: JSON array of { judge_id, score, passed } from each Judge
+#   - aggregated_score: float, output of tribunal_aggregate
+#   - score_threshold: float from the active rubric
+#   - meta: JSON of the Meta-Judge's TribunalMetaCompletePayload (for bias_detected
+#           and override_recommendation)
+#   - dissent_score: float, output of tribunal_disagreement
+#   - dissent_threshold: float from rubric/config
+#
+# Echoes a JSON object: { passed: bool, reason?: string }
+#   reason is one of: low_score | meta_override | bias_detected | dissent_unresolved
+#
+# Usage: result=$(tribunal_gate_decide "$policy" "$verdicts" "$agg" "$thr" "$meta" "$dissent" "$dissent_thr")
+
+tribunal_gate_decide() {
+	local policy="${1:-majority}"
+	local verdicts="${2:-[]}"
+	local aggregated_score="${3:-0}"
+	local score_threshold="${4:-0.75}"
+	local meta="${5:-{}}"
+	local dissent_score="${6:-0}"
+	local dissent_threshold="${7:-0.25}"
+
+	local meta_bias_detected meta_override
+	meta_bias_detected=$(printf '%s' "$meta" | jq -r '.bias_detected // false' 2>/dev/null)
+	meta_override=$(printf '%s' "$meta" | jq -r '.override_recommendation // empty' 2>/dev/null)
+
+	# meta_override policy: the Meta-Judge wins, regardless of jury.
+	if [[ "$policy" == "meta_override" ]]; then
+		case "$meta_override" in
+			accept)
+				printf '{"passed":true}'
+				return 0
+				;;
+			reject)
+				printf '{"passed":false,"reason":"meta_override"}'
+				return 0
+				;;
+			re-evaluate|"")
+				# No clear override → fall through to score-based decision.
+				;;
+		esac
+	fi
+
+	# Bias detection short-circuit (any policy).
+	if [[ "$meta_bias_detected" == "true" && "$meta_override" == "reject" ]]; then
+		printf '{"passed":false,"reason":"bias_detected"}'
+		return 0
+	fi
+
+	# Dissent short-circuit: if judges disagree past threshold AND the Meta-Judge
+	# has not provided an override, block with dissent_unresolved so the loop
+	# retries with a fresh Actor pass.
+	if awk -v d="$dissent_score" -v t="$dissent_threshold" 'BEGIN { exit !(d > t) }' \
+		&& [[ -z "$meta_override" || "$meta_override" == "re-evaluate" ]]; then
+		printf '{"passed":false,"reason":"dissent_unresolved"}'
+		return 0
+	fi
+
+	local count passed_count
+	count=$(printf '%s' "$verdicts" | jq 'length' 2>/dev/null) || count=0
+	passed_count=$(printf '%s' "$verdicts" | jq '[.[] | select(.passed == true)] | length' 2>/dev/null) || passed_count=0
+
+	local jury_ok=1  # 0 = ok, 1 = not ok (shell convention)
+	case "$policy" in
+		strict|unanimous)
+			[[ "$count" -gt 0 && "$passed_count" -eq "$count" ]] && jury_ok=0
+			;;
+		majority)
+			# strictly greater than half
+			[[ "$count" -gt 0 ]] && (( passed_count * 2 > count )) && jury_ok=0
+			;;
+		meta_override)
+			# Already handled accept/reject above; fall back to majority for the
+			# re-evaluate / unset case.
+			[[ "$count" -gt 0 ]] && (( passed_count * 2 > count )) && jury_ok=0
+			;;
+		*)
+			printf 'tribunal-gate: unknown policy %s, falling back to majority\n' \
+				"$policy" >&2
+			[[ "$count" -gt 0 ]] && (( passed_count * 2 > count )) && jury_ok=0
+			;;
+	esac
+
+	local score_ok=1
+	awk -v s="$aggregated_score" -v t="$score_threshold" 'BEGIN { exit !(s >= t) }' && score_ok=0
+
+	if [[ "$jury_ok" -eq 0 && "$score_ok" -eq 0 ]]; then
+		printf '{"passed":true}'
+		return 0
+	fi
+
+	# Pick the most informative blocking reason.
+	if [[ "$score_ok" -ne 0 ]]; then
+		printf '{"passed":false,"reason":"low_score"}'
+	else
+		# Jury did not pass even though score cleared threshold — surface as
+		# meta_override when meta said reject, else dissent_unresolved.
+		if [[ "$meta_override" == "reject" ]]; then
+			printf '{"passed":false,"reason":"meta_override"}'
+		else
+			printf '{"passed":false,"reason":"dissent_unresolved"}'
+		fi
+	fi
+}

package/plugins/tribunal/scripts/lib/tribunal-jury.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Jury resolution for Tribunal.
+#
+# Maps a list of judge_types (from a rubric or config) into a panel of judges
+# the orchestrator can spawn. Each panel entry carries:
+#   - judge_id: ULID, unique per panel member
+#   - judge_type: schema enum (standard, security, maintainability, adversarial,
+#                 domain, meta)
+#   - subagent: name of the subagent MD to invoke
+#   - model: resolved per-judge-type model from config
+#
+# Two judge_types are recognized by schema but not yet shipped as subagents:
+# `maintainability` and `domain`. The jury degrades them to `standard` and emits
+# a warning on stderr so the orchestrator can log it.
+#
+# Requires tribunal-config.sh and tribunal-ulid.sh to be sourced.
+
+# Map a judge_type to the shipped subagent name. Echoes empty if there is no
+# shipped subagent.
+_tribunal_jury_subagent_for_type() {
+	case "$1" in
+		standard)    printf 'tribunal-judge-standard' ;;
+		security)    printf 'tribunal-judge-security' ;;
+		adversarial) printf 'tribunal-judge-adversarial' ;;
+		meta)        printf 'tribunal-meta-judge' ;;
+		*) return 0 ;;
+	esac
+}
+
+# Build a jury from a JSON array of judge_types.
+# Echoes a JSON array of { judge_id, judge_type, subagent, model } objects.
+# Unsupported types (maintainability, domain) are remapped to standard with a
+# warning on stderr.
+#
+# Usage: jury=$(tribunal_jury_empanel '["standard","adversarial"]')
+tribunal_jury_empanel() {
+	local types_json="${1:-[]}"
+	[[ -z "$types_json" ]] && types_json="[]"
+
+	local panel='[]'
+	local count
+	count=$(printf '%s' "$types_json" | jq 'length' 2>/dev/null) || count=0
+
+	local i raw_type judge_type subagent model judge_id
+	for ((i = 0; i < count; i++)); do
+		raw_type=$(printf '%s' "$types_json" | jq -r ".[$i]" 2>/dev/null) || continue
+		[[ -z "$raw_type" || "$raw_type" == "null" ]] && continue
+
+		# Schema-known types we don't ship yet degrade to standard.
+		case "$raw_type" in
+			maintainability|domain)
+				printf 'tribunal-jury: judge_type "%s" not shipped in v0.1, degrading to standard\n' \
+					"$raw_type" >&2
+				judge_type="standard"
+				;;
+			meta)
+				# Meta is the Meta-Judge — never goes in the jury panel.
+				printf 'tribunal-jury: refusing to add judge_type "meta" to the jury (meta is the Meta-Judge)\n' >&2
+				continue
+				;;
+			standard|security|adversarial)
+				judge_type="$raw_type"
+				;;
+			*)
+				printf 'tribunal-jury: unknown judge_type "%s", degrading to standard\n' \
+					"$raw_type" >&2
+				judge_type="standard"
+				;;
+		esac
+
+		subagent=$(_tribunal_jury_subagent_for_type "$judge_type")
+		[[ -z "$subagent" ]] && continue
+
+		model=$(tribunal_config_judge_model "$judge_type")
+		judge_id=$(tribunal_ulid)
+
+		panel=$(printf '%s' "$panel" | jq -c \
+			--arg id "$judge_id" \
+			--arg type "$judge_type" \
+			--arg sub "$subagent" \
+			--arg model "$model" \
+			'. + [{
+				judge_id: $id,
+				judge_type: $type,
+				subagent: $sub,
+				model: (if $model == "" then null else $model end)
+			}]')
+	done
+
+	printf '%s' "$panel"
+}
+
+# Render a jury into the schema's TribunalJuryEmpaneledPayload.judges shape:
+# [{ judge_id, judge_type, model_id }, ...]
+tribunal_jury_to_schema_judges() {
+	local panel="${1:-[]}"
+	printf '%s' "$panel" | jq -c '[.[] | {
+		judge_id: .judge_id,
+		judge_type: .judge_type,
+		model_id: .model
+	} | with_entries(select(.value != null))]'
+}

package/plugins/tribunal/scripts/lib/tribunal-project-key.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Project key derivation for Tribunal.
+#
+# Mirrors the archivist project-key scheme so the two plugins partition storage
+# identically. A project key is a stable 12-char hex identifier that survives:
+#   - local rename of the repo directory
+#   - cloning the same repo to a different path on the same machine
+#   - moving the repo between machines (as long as the git remote is preserved)
+#   - worktrees (a worktree shares its parent repo's key)
+#
+# Resolution order:
+#   1. SHA256(`git remote get-url origin`) — preferred, machine-portable
+#   2. SHA256(realpath of `git rev-parse --show-toplevel`) — fallback for repos
+#      without an origin remote (greenfield local-only work)
+#
+# Returns the first 12 hex chars. Returns empty string if neither resolution
+# path works.
+
+_tribunal_sha256_first12() {
+	local input="$1"
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$input" | shasum -a 256 2>/dev/null | cut -c1-12
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$input" | sha256sum 2>/dev/null | cut -c1-12
+	else
+		return 1
+	fi
+}
+
+tribunal_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+# Worktree-aware: uses common-dir so worktrees share a key with the main repo.
+tribunal_project_repo_root() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+
+	if ! git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+
+	if [[ -n "$common_dir" && "$common_dir" != /* ]]; then
+		common_dir="$(cd "$cwd" && cd "$common_dir" 2>/dev/null && pwd -P)" || common_dir=""
+	fi
+
+	if [[ -n "$common_dir" && -d "$common_dir" ]]; then
+		toplevel="$(cd "$common_dir/.." 2>/dev/null && pwd -P)" || toplevel=""
+	fi
+
+	if [[ -z "$toplevel" ]]; then
+		toplevel=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null || true)
+		[[ -n "$toplevel" ]] && toplevel="$(cd "$toplevel" 2>/dev/null && pwd -P)"
+	fi
+
+	printf '%s' "$toplevel"
+}
+
+# Compute the project key for the given cwd. Prints the key or empty string.
+tribunal_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(tribunal_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_tribunal_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(tribunal_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_tribunal_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}

package/plugins/tribunal/scripts/lib/tribunal-rubric.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# Rubric resolution for Tribunal.
+#
+# Layered lookup (latest wins, by rubric id):
+#   1. Built-in rubrics from plugins/tribunal/config.json (.tribunal.rubric.builtins)
+#   2. ~/.onlooker/tribunal.json (.rubrics)
+#   3. <repo>/.claude/tribunal.json (.rubrics)
+#
+# Exposes:
+#   tribunal_rubric_load <repo_root>         # populates _TRIBUNAL_RUBRICS (JSON array)
+#   tribunal_rubric_get <id>                 # echoes a single rubric as JSON, or empty
+#   tribunal_rubric_default_id               # default rubric id from config
+#   tribunal_rubric_validate <rubric_json>   # exits 0 if valid, 1 otherwise; prints reasons to stderr
+#
+# Schema:
+#   {
+#     "id": "default",
+#     "criteria": [ { "name": str, "weight": [0,1], "min_pass": [0,1] }, ... ],
+#     "score_threshold": [0,1],
+#     "max_iterations": int >= 1,
+#     "judge_types": ["standard" | "security" | ...],
+#     "gate_policy": "strict" | "majority" | "unanimous" | "meta_override",
+#     "aggregation_method": "mean" | "median" | "min" | "weighted_mean"
+#   }
+#
+# Requires tribunal-config.sh to be sourced and tribunal_config_load to have run.
+
+_TRIBUNAL_RUBRICS="[]"
+
+_tribunal_rubric_overlay_file() {
+	local file="$1"
+	local base="$2"
+	[[ -f "$file" ]] || { printf '%s' "$base"; return 0; }
+	local overlay
+	overlay=$(jq -c '.rubrics // []' "$file" 2>/dev/null) || { printf '%s' "$base"; return 0; }
+	[[ "$overlay" == "[]" || -z "$overlay" ]] && { printf '%s' "$base"; return 0; }
+
+	jq -c -n --argjson base "$base" --argjson overlay "$overlay" '
+		($base + $overlay)
+		| reduce .[] as $r ({}; .[$r.id] = $r)
+		| [.[]]
+	'
+}
+
+tribunal_rubric_load() {
+	local repo_root="${1:-}"
+	local home_dir="${HOME:-}"
+
+	local builtins
+	builtins=$(printf '%s' "$_TRIBUNAL_CONFIG" | jq -c '.tribunal.rubric.builtins // []' 2>/dev/null)
+	[[ -z "$builtins" ]] && builtins="[]"
+
+	local merged="$builtins"
+	merged=$(_tribunal_rubric_overlay_file "${home_dir}/.onlooker/tribunal.json" "$merged")
+	merged=$(_tribunal_rubric_overlay_file "${repo_root}/.claude/tribunal.json" "$merged")
+
+	_TRIBUNAL_RUBRICS="$merged"
+}
+
+tribunal_rubric_default_id() {
+	local id
+	id=$(tribunal_config_get '.tribunal.rubric.default_id')
+	[[ -z "$id" ]] && id="default"
+	printf '%s' "$id"
+}
+
+tribunal_rubric_get() {
+	local id="$1"
+	[[ -z "$id" ]] && return 0
+	printf '%s' "$_TRIBUNAL_RUBRICS" | jq -c --arg id "$id" \
+		'map(select(.id == $id)) | first // empty' 2>/dev/null
+}
+
+# Validate a single rubric JSON blob. Prints reasons to stderr; exits 1 on first
+# problem so callers can pipe to a single failure path.
+tribunal_rubric_validate() {
+	local rubric="${1:-}"
+	[[ -z "$rubric" || "$rubric" == "null" ]] && {
+		printf 'rubric is empty\n' >&2
+		return 1
+	}
+
+	local id
+	id=$(printf '%s' "$rubric" | jq -r '.id // empty' 2>/dev/null)
+	[[ -z "$id" ]] && { printf 'rubric missing .id\n' >&2; return 1; }
+
+	local criteria_count
+	criteria_count=$(printf '%s' "$rubric" | jq -r '(.criteria // []) | length' 2>/dev/null)
+	[[ "$criteria_count" -ge 1 ]] || {
+		printf 'rubric %s: criteria must be non-empty\n' "$id" >&2
+		return 1
+	}
+
+	# Each criterion: name non-empty, weight in [0,1], min_pass in [0,1].
+	local bad_crit
+	bad_crit=$(printf '%s' "$rubric" | jq -r '
+		[.criteria[]
+		 | select(
+			 (.name | type) != "string"
+			 or (.name | length) == 0
+			 or (.weight | type) != "number" or .weight < 0 or .weight > 1
+			 or (.min_pass | type) != "number" or .min_pass < 0 or .min_pass > 1
+		   )
+		 | .name // "(unnamed)"]
+		| join(",")
+	' 2>/dev/null)
+	[[ -n "$bad_crit" ]] && {
+		printf 'rubric %s: invalid criteria: %s\n' "$id" "$bad_crit" >&2
+		return 1
+	}
+
+	# Weights must sum to ~1.0.
+	local weight_sum
+	weight_sum=$(printf '%s' "$rubric" | jq -r '[.criteria[].weight] | add' 2>/dev/null)
+	awk -v s="$weight_sum" 'BEGIN { exit !(s > 0.99 && s < 1.01) }' || {
+		printf 'rubric %s: criterion weights sum to %s (expected ~1.0)\n' "$id" "$weight_sum" >&2
+		return 1
+	}
+
+	# score_threshold in [0,1].
+	local thr
+	thr=$(printf '%s' "$rubric" | jq -r '.score_threshold // 0.75' 2>/dev/null)
+	awk -v t="$thr" 'BEGIN { exit !(t >= 0 && t <= 1) }' || {
+		printf 'rubric %s: score_threshold %s out of [0,1]\n' "$id" "$thr" >&2
+		return 1
+	}
+
+	# gate_policy enum.
+	local gp
+	gp=$(printf '%s' "$rubric" | jq -r '.gate_policy // "majority"' 2>/dev/null)
+	case "$gp" in
+		strict|majority|unanimous|meta_override) : ;;
+		*) printf 'rubric %s: invalid gate_policy %s\n' "$id" "$gp" >&2; return 1 ;;
+	esac
+
+	# aggregation_method enum.
+	local am
+	am=$(printf '%s' "$rubric" | jq -r '.aggregation_method // "weighted_mean"' 2>/dev/null)
+	case "$am" in
+		mean|median|min|weighted_mean) : ;;
+		*) printf 'rubric %s: invalid aggregation_method %s\n' "$id" "$am" >&2; return 1 ;;
+	esac
+
+	# max_iterations integer >= 1.
+	local mi
+	mi=$(printf '%s' "$rubric" | jq -r '.max_iterations // 3' 2>/dev/null)
+	[[ "$mi" =~ ^[0-9]+$ && "$mi" -ge 1 ]] || {
+		printf 'rubric %s: max_iterations must be integer >= 1 (got %s)\n' "$id" "$mi" >&2
+		return 1
+	}
+
+	return 0
+}

package/plugins/tribunal/scripts/lib/tribunal-ulid.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for Tribunal task_id and iteration_id values.
+#
+# Spec: https://github.com/ulid/spec
+#   - 48-bit timestamp (ms since epoch) → 10 chars Crockford Base32
+#   - 80-bit randomness → 16 chars Crockford Base32
+#   - lexicographically sortable, time-ordered
+
+_TRIBUNAL_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_tribunal_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_TRIBUNAL_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+tribunal_ulid() {
+	local now_ms
+	if [[ "$(uname)" == "Darwin" ]]; then
+		now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+			|| now_ms=$(($(date +%s) * 1000))
+	else
+		now_ms=$(date +%s%3N 2>/dev/null) || now_ms=$(($(date +%s) * 1000))
+	fi
+
+	local rand_hex rand_hi rand_lo
+	rand_hex=$(openssl rand -hex 10 2>/dev/null)
+	if [[ -n "$rand_hex" && ${#rand_hex} -eq 20 ]]; then
+		rand_hi=$((16#${rand_hex:0:10}))
+		rand_lo=$((16#${rand_hex:10:10}))
+	else
+		rand_hi=$((RANDOM * 32768 + RANDOM))
+		rand_lo=$((RANDOM * 32768 + RANDOM))
+		rand_hi=$(((rand_hi * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+		rand_lo=$(((rand_lo * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+	fi
+
+	local ts_part hi_part lo_part
+	ts_part=$(_tribunal_ulid_encode "$now_ms" 10)
+	hi_part=$(_tribunal_ulid_encode "$rand_hi" 8)
+	lo_part=$(_tribunal_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/plugins/tribunal/scripts/lib/tribunal-verdict.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# Verdict persistence for Tribunal.
+#
+# Writes per-iteration artifacts under:
+#   $ONLOOKER_DIR/tribunal/<project-key>/<task_id>/iteration-<iteration_id>/
+#     actor.md
+#     jury.json
+#     verdicts/<judge_id>.json
+#     consensus.json
+#     dissent.json   (optional)
+#     meta.json
+#     gate.json
+#
+# Plus task-level files at <task_id>/{manifest,session-start,session-complete}.json.
+#
+# Requires tribunal-project-key.sh to be sourced.
+
+tribunal_storage_root() {
+	local base="${ONLOOKER_DIR:-$HOME/.onlooker}"
+	printf '%s/tribunal' "$base"
+}
+
+tribunal_project_dir() {
+	local key="$1"
+	printf '%s/%s' "$(tribunal_storage_root)" "$key"
+}
+
+tribunal_task_dir() {
+	local key="$1"
+	local task_id="$2"
+	printf '%s/%s' "$(tribunal_project_dir "$key")" "$task_id"
+}
+
+tribunal_iteration_dir() {
+	local key="$1"
+	local task_id="$2"
+	local iteration_id="$3"
+	printf '%s/iteration-%s' "$(tribunal_task_dir "$key" "$task_id")" "$iteration_id"
+}
+
+tribunal_init_task() {
+	local key="$1"
+	local task_id="$2"
+	[[ -z "$key" || -z "$task_id" ]] && return 1
+	mkdir -p "$(tribunal_task_dir "$key" "$task_id")" 2>/dev/null
+}
+
+tribunal_init_iteration() {
+	local key="$1"
+	local task_id="$2"
+	local iteration_id="$3"
+	[[ -z "$key" || -z "$task_id" || -z "$iteration_id" ]] && return 1
+	mkdir -p "$(tribunal_iteration_dir "$key" "$task_id" "$iteration_id")/verdicts" 2>/dev/null
+}
+
+# Write the project-level manifest (one per project key, refreshed each task).
+tribunal_write_project_manifest() {
+	local key="$1"
+	local remote_url="$2"
+	local repo_root="$3"
+	[[ -z "$key" ]] && return 1
+	mkdir -p "$(tribunal_project_dir "$key")" 2>/dev/null
+
+	local now
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	jq -n \
+		--arg key "$key" \
+		--arg remote "$remote_url" \
+		--arg root "$repo_root" \
+		--arg now "$now" \
+		'{
+			project_key: $key,
+			remote_url: (if $remote == "" then null else $remote end),
+			repo_root: (if $root == "" then null else $root end),
+			last_task_at: $now,
+			source: "local"
+		}' > "$(tribunal_project_dir "$key")/manifest.json"
+}
+
+# Write the per-task manifest with the active rubric snapshot.
+tribunal_write_task_manifest() {
+	local key="$1"
+	local task_id="$2"
+	local task_summary="$3"
+	local rubric_id="$4"
+	local rubric_json="$5"
+	[[ -z "$key" || -z "$task_id" ]] && return 1
+	tribunal_init_task "$key" "$task_id" || return 1
+
+	local now
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	jq -n \
+		--arg task_id "$task_id" \
+		--arg summary "$task_summary" \
+		--arg rubric_id "$rubric_id" \
+		--argjson rubric "$rubric_json" \
+		--arg now "$now" \
+		'{
+			task_id: $task_id,
+			task_summary: $summary,
+			rubric_id: $rubric_id,
+			rubric: $rubric,
+			started_at: $now
+		}' > "$(tribunal_task_dir "$key" "$task_id")/manifest.json"
+}
+
+# Append-time helpers for each per-iteration artifact. Each takes the full JSON
+# blob the caller wants persisted (typically the same payload it just emitted as
+# a canonical event).
+tribunal_write_actor_output() {
+	local key="$1" task_id="$2" iteration_id="$3" body="$4"
+	tribunal_init_iteration "$key" "$task_id" "$iteration_id" || return 1
+	printf '%s\n' "$body" > "$(tribunal_iteration_dir "$key" "$task_id" "$iteration_id")/actor.md"
+}
+
+tribunal_write_iteration_artifact() {
+	local key="$1" task_id="$2" iteration_id="$3" name="$4" json="$5"
+	tribunal_init_iteration "$key" "$task_id" "$iteration_id" || return 1
+	printf '%s\n' "$json" > "$(tribunal_iteration_dir "$key" "$task_id" "$iteration_id")/${name}.json"
+}
+
+tribunal_write_judge_verdict() {
+	local key="$1" task_id="$2" iteration_id="$3" judge_id="$4" verdict_json="$5"
+	tribunal_init_iteration "$key" "$task_id" "$iteration_id" || return 1
+	printf '%s\n' "$verdict_json" \
+		> "$(tribunal_iteration_dir "$key" "$task_id" "$iteration_id")/verdicts/${judge_id}.json"
+}