@onlooker-community/ecosystem 0.34.0 → 0.43.0

package/plugins/librarian/scripts/lib/librarian-cli.sh

@@ -3,6 +3,7 @@
 #
 # Exposes:
 #   librarian_cli list                         # one-line summary + table of pending proposals
+#   librarian_cli lessons list [--confirmed]   # pending lesson queue, or the confirmed ones
 #   librarian_cli show <proposal_id>           # full proposal body + provenance + conflict state
 #   librarian_cli accept <proposal_id>         # write to typed memory store, mark accepted
 #   librarian_cli reject <proposal_id> [reason]  # tombstone + mark rejected
@@ -18,7 +19,11 @@
 # bullet line, and the file is created if it doesn't exist.
 #
 # Depends on (sourced by the caller): librarian-config.sh,
-# librarian-project-key.sh, librarian-storage.sh, librarian-emit.sh
+# librarian-project-key.sh, librarian-storage.sh, librarian-emit.sh,
+# librarian-lesson-storage.sh, librarian-lesson-validate.sh,
+# librarian-lesson-review.sh, librarian-lesson-judge.sh,
+# librarian-lesson-rubric.sh, librarian-author-key.sh,
+# librarian-lesson-promote.sh
 
 # ----------------------------------------------------------------------------
 # Project key + memory store path resolution
@@ -117,7 +122,8 @@ _librarian_cli_set_proposal_status() {
 	local key="$1"
 	local proposal_id="$2"
 	local new_status="$3"
-	local extra_json="${4:-{\}}"
+	local extra_json="${4:-}"
+	[ -z "$extra_json" ] && extra_json='{}'
 	[[ -z "$key" || -z "$proposal_id" || -z "$new_status" ]] && return 1
 
 	local path
@@ -324,6 +330,343 @@ librarian_cli_status() {
 	printf 'pending: %s, accepted: %s, rejected: %s\n' "$pending" "$accepted" "$rejected"
 }
 
+# ----------------------------------------------------------------------------
+# Lesson confirmation surface
+#
+# Namespaced under `lessons` and kept apart from the memory verbs on purpose.
+# Accepting a memory writes a file on this machine; confirming a lesson commits
+# it toward leaving this machine, irreversibly once synced. Those two decisions
+# should not sit one keystroke apart.
+# ----------------------------------------------------------------------------
+
+# Usage: librarian_cli_lessons_list [--confirmed] [cwd]
+#
+# Bare `list` shows the pending queue the review walk drives. `--confirmed`
+# shows lessons already confirmed and not yet judged, which is otherwise
+# undiscoverable: unconfirm operates only on a `confirmed` lesson, and the
+# pending list by definition never contains one. Without this view a human who
+# confirmed at the wrong visibility last session has no way back to the id.
+librarian_cli_lessons_list() {
+	local status="pending" cwd="" json=0
+	while [[ $# -gt 0 ]]; do
+		case "$1" in
+			--confirmed) status="confirmed"; shift ;;
+			--json) json=1; shift ;;
+			--*)
+				# Same contract as the sibling verbs: an unrecognized flag is
+				# refused rather than falling through to the cwd bucket, where
+				# it would resolve no project key and report a path problem the
+				# caller does not have.
+				printf 'unknown option: %s\n' "$1" >&2
+				return 1
+				;;
+			*) cwd="$1"; shift ;;
+		esac
+	done
+
+	local key rows
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+	rows=$(librarian_lesson_list_by_status "$key" "$status")
+
+	# Checked before the empty-set branch below: the skill parses this output,
+	# and an empty result must still emit `[]`, not the prose empty-state
+	# message that follows.
+	if [[ "$json" -eq 1 ]]; then
+		printf '%s' "$rows"
+		return 0
+	fi
+
+	if [[ "$(printf '%s' "$rows" | jq 'length')" -eq 0 ]]; then
+		printf 'No %s lessons.\n' "$status"
+		return 0
+	fi
+	printf '%s' "$rows" | jq -r '.[] | "\(.id)  \(.candidate.claim)"'
+}
+
+librarian_cli_lessons_show() {
+	local lesson_id="${1:-}"
+	local cwd="${2:-}"
+	[[ -z "$lesson_id" ]] && { printf 'usage: librarian_cli lessons show <lesson_id>\n'; return 1; }
+
+	local key path
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+	path="$(librarian_lessons_dir "$key")/proposals/${lesson_id}.json"
+	[[ -f "$path" ]] || { printf 'Lesson %s not found.\n' "$lesson_id"; return 1; }
+
+	# visibility sits next to status because the two are read together: it is
+	# the field a human needs to check before deciding whether to unconfirm,
+	# and it is only set on a confirmed lesson. A pending one renders `—`
+	# rather than a jq `null`, so the absence reads as "not decided yet".
+	jq -r '
+		"id:          \(.id)",
+		"status:      \(.status)",
+		"visibility:  \(.visibility // "—")",
+		"artifact:    \(.artifact_id)",
+		"claim:       \(.candidate.claim)",
+		"rationale:   \(.candidate.rationale)",
+		"resolution:  \(.candidate.evidence.resolution)",
+		"stack:       \(.candidate.applies_to.stack | join(", "))",
+		"scope:       \(.candidate.applies_to.scope | tojson)"
+	' "$path"
+}
+
+librarian_cli_lessons_confirm() {
+	local lesson_id="${1:-}"
+	local visibility="${2:-}"
+	[[ -z "$lesson_id" || -z "$visibility" ]] && {
+		printf 'usage: librarian_cli lessons confirm <lesson_id> <private|org|public> [--justification TEXT] [cwd]\n'
+		return 1
+	}
+	shift 2
+
+	# --justification is a named flag, not a position. This is the verb that
+	# commits a lesson toward leaving this machine, so a caller who supplies
+	# cwd but omits justification must never have cwd silently misread as the
+	# justification that flips scope to version_independent.
+	local justification="" justification_given=0 cwd=""
+	while [[ $# -gt 0 ]]; do
+		case "$1" in
+			--justification)
+				justification="${2:-}"
+				justification_given=1
+				if [[ $# -ge 2 ]]; then
+					shift 2
+				else
+					shift 1
+				fi
+				;;
+			--*)
+				# An unrecognized flag must never fall through to the cwd
+				# bucket below: a typo'd --justifcation would otherwise be
+				# swallowed here, its value would land as a plain positional
+				# (misread as cwd, then overwritten by the real trailing
+				# path), and the lesson would confirm with an empty
+				# justification and no diagnostic — a persisted wrong state
+				# this CLI has no verb to undo.
+				printf 'unknown option: %s\n' "$1" >&2
+				return 1
+				;;
+			*)
+				cwd="$1"
+				shift
+				;;
+		esac
+	done
+
+	# A justification that is blank after trimming whitespace is refused
+	# outright rather than silently treated as "no justification supplied" —
+	# the validator's minLength: 1 counts whitespace, so passing it through
+	# would flip scope to version_independent on content nobody actually
+	# wrote.
+	if [[ "$justification_given" -eq 1 ]] && [[ "$justification" =~ ^[[:space:]]*$ ]]; then
+		printf 'justification is blank after trimming whitespace; omit --justification instead of passing an empty value.\n' >&2
+		return 1
+	fi
+
+	local key
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+
+	librarian_lesson_confirm "$key" "$lesson_id" "$visibility" "$justification" || return 1
+	printf 'Confirmed %s at %s visibility.\n' "$lesson_id" "$visibility"
+}
+
+librarian_cli_lessons_pass() {
+	local lesson_id="${1:-}"
+	local reason="${2:-}"
+	local cwd="${3:-}"
+	[[ -z "$lesson_id" ]] && { printf 'usage: librarian_cli lessons pass <lesson_id> [reason]\n'; return 1; }
+
+	# reason and cwd are positional, not flags — but a flag-shaped token here
+	# is almost always a typo for confirm's `--justification` (the likeliest
+	# guess is `--reason`). Reject it rather than silently accepting it as
+	# the literal reason: librarian_lesson_pass writes to the append-only
+	# passed.jsonl ledger with no CLI verb to correct a bad line afterward.
+	case "$reason" in
+		--*) printf 'unknown option: %s\n' "$reason" >&2; return 1 ;;
+	esac
+	case "$cwd" in
+		--*) printf 'unknown option: %s\n' "$cwd" >&2; return 1 ;;
+	esac
+
+	local key
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+
+	librarian_lesson_pass "$key" "$lesson_id" "$reason" || return 1
+	printf 'Passed on %s.\n' "$lesson_id"
+}
+
+librarian_cli_lessons_unconfirm() {
+	local lesson_id="${1:-}"
+	local cwd="${2:-}"
+	[[ -z "$lesson_id" ]] && { printf 'usage: librarian_cli lessons unconfirm <lesson_id>\n'; return 1; }
+
+	# Reject a flag-shaped token rather than treating it as cwd. The sibling
+	# verbs already do this; a stray flag absorbed as a path resolves to the
+	# wrong project key and the verb then reports success against a lesson it
+	# never touched. Here that write-safety case can't actually arise — cwd
+	# is the last positional, so an invalid one (e.g. "--force") already
+	# fails project-key resolution below and returns 1 with no write. This
+	# guard is a diagnostic, not a write guard: it swaps that generic "No
+	# project key resolvable" for "unknown option: --force" so the caller
+	# isn't sent hunting a path problem they don't have. Keep it for that
+	# reason even though it looks redundant next to confirm's and pass's.
+	case "$cwd" in
+		--*) printf 'unknown option: %s\n' "$cwd" >&2; return 1 ;;
+	esac
+
+	local key
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+
+	# Read the status before the call so the message can tell "took back a
+	# confirmation" apart from "it was already pending". librarian_lesson_unconfirm
+	# returns 0 for both by design — 0 means "the lesson is pending now" — and
+	# keeping that contract single-valued is what lets callers stay simple, so
+	# the distinction is made here rather than by widening the return.
+	#
+	# A status changing between this read and the call can only misword the
+	# message; the write itself is guarded inside librarian_lesson_unconfirm,
+	# which re-reads the file and refuses anything that is not `confirmed`.
+	local prior_status
+	prior_status=$(jq -r '.status // ""' \
+		"$(librarian_lessons_dir "$key")/proposals/${lesson_id}.json" 2>/dev/null)
+
+	librarian_lesson_unconfirm "$key" "$lesson_id" || return 1
+	if [[ "$prior_status" == "pending" ]]; then
+		printf 'Lesson %s was already pending; nothing to take back.\n' "$lesson_id"
+	else
+		printf 'Unconfirmed %s; it is pending again.\n' "$lesson_id"
+	fi
+}
+
+# Usage: librarian_cli_lessons_judge <lesson_id> <verdicts-json> [cwd]
+#
+# Verdicts come from the judge subagents the skill dispatched. Exit 2 means the
+# candidate could not be judged and stays confirmed — distinct from a rejection,
+# which is a real verdict and exits 0.
+librarian_cli_lessons_judge() {
+	local lesson_id="" verdicts="" cwd=""
+	local positional=0
+	while [[ $# -gt 0 ]]; do
+		case "$1" in
+			--*)
+				printf 'unknown option: %s\n' "$1" >&2
+				return 1
+				;;
+			*)
+				case "$positional" in
+					0) lesson_id="$1" ;;
+					1) verdicts="$1" ;;
+					*) cwd="$1" ;;
+				esac
+				positional=$((positional + 1))
+				shift
+				;;
+		esac
+	done
+
+	if [[ -z "$lesson_id" || -z "$verdicts" ]]; then
+		printf 'usage: librarian_cli lessons judge <lesson_id> <verdicts-json> [cwd]\n'
+		return 1
+	fi
+
+	local key
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+
+	librarian_lesson_judge "$key" "$lesson_id" "$verdicts"
+	local rc=$?
+	case "$rc" in
+		0)
+			printf 'Lesson %s is now %s.\n' "$lesson_id" \
+				"$(jq -r '.status' "$(librarian_lessons_dir "$key")/proposals/${lesson_id}.json")"
+			# Promotion failing does not undo a correct verdict: report it and
+			# leave the lesson promotable by a standalone `lessons promote`.
+			librarian_lesson_promote "$key" "$lesson_id" \
+				|| printf 'Lesson %s was judged but not promoted; run `lessons promote %s` to retry.\n' \
+					"$lesson_id" "$lesson_id"
+			;;
+		2)
+			printf 'Lesson %s could not be judged; it stays confirmed. Re-run to retry.\n' "$lesson_id"
+			;;
+		*)
+			printf 'Lesson %s could not be judged (exit %d); see above.\n' "$lesson_id" "$rc"
+			;;
+	esac
+	return $rc
+}
+
+# Usage: librarian_cli_lessons_promote <lesson_id> [cwd]
+#
+# Runnable standalone on purpose: promotion fails for reasons judging does not
+# — a malformed author secret, absent node, a full disk — and a standalone run
+# is how a correctly-judged, not-yet-promoted lesson gets reconciled.
+librarian_cli_lessons_promote() {
+	local lesson_id="" cwd=""
+	local positional=0
+	while [[ $# -gt 0 ]]; do
+		case "$1" in
+			--*)
+				printf 'unknown option: %s\n' "$1" >&2
+				return 1
+				;;
+			*)
+				case "$positional" in
+					0) lesson_id="$1" ;;
+					*) cwd="$1" ;;
+				esac
+				positional=$((positional + 1))
+				shift
+				;;
+		esac
+	done
+
+	[[ -z "$lesson_id" ]] && { printf 'usage: librarian_cli lessons promote <lesson_id> [cwd]\n'; return 1; }
+
+	local key
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+
+	librarian_lesson_promote "$key" "$lesson_id" || return 1
+	printf 'Lesson %s promoted.\n' "$lesson_id"
+}
+
+librarian_cli_lessons_defer() {
+	local lesson_id="${1:-}"
+	[[ -z "$lesson_id" ]] && { printf 'usage: librarian_cli lessons defer <lesson_id>\n'; return 1; }
+	printf 'Deferred %s; it stays in the queue.\n' "$lesson_id"
+}
+
+librarian_cli_lessons_status() {
+	local cwd="${1:-}"
+	local key pending
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+	pending=$(librarian_lesson_list_pending "$key")
+	printf 'lessons pending: %s\n' "$(printf '%s' "$pending" | jq 'length')"
+}
+
+librarian_cli_lessons() {
+	local verb="${1:-list}"
+	shift || true
+	case "$verb" in
+		list) librarian_cli_lessons_list "$@" ;;
+		show) librarian_cli_lessons_show "$@" ;;
+		confirm) librarian_cli_lessons_confirm "$@" ;;
+		pass) librarian_cli_lessons_pass "$@" ;;
+		unconfirm) librarian_cli_lessons_unconfirm "$@" ;;
+		judge) librarian_cli_lessons_judge "$@" ;;
+		promote) librarian_cli_lessons_promote "$@" ;;
+		defer) librarian_cli_lessons_defer "$@" ;;
+		status) librarian_cli_lessons_status "$@" ;;
+		*) printf 'unknown lessons action: %s\n' "$verb"; return 2 ;;
+	esac
+}
+
 librarian_cli() {
 	local action="${1:-list}"
 	shift || true
@@ -334,6 +677,7 @@ librarian_cli() {
 		reject) librarian_cli_reject "$@" ;;
 		defer) librarian_cli_defer "$@" ;;
 		status) librarian_cli_status "$@" ;;
+		lessons) librarian_cli_lessons "$@" ;;
 		*) printf 'unknown action: %s\n' "$action"; return 2 ;;
 	esac
 }

package/plugins/librarian/scripts/lib/librarian-emit.sh

@@ -50,7 +50,8 @@ _LIBRARIAN_EVENT_JS="${_LIBRARIAN_EVENT_JS:-$(_librarian_resolve_event_js)}"
 librarian_emit() {
 	local event_type="${1:-}"
 	local session_id="${2:-}"
-	local payload="${3:-{\}}"
+	local payload="${3:-}"
+	[ -z "$payload" ] && payload='{}'
 
 	[[ -z "$event_type" || -z "$session_id" ]] && return 0
 	[[ -z "$_LIBRARIAN_EVENT_JS" || ! -f "$_LIBRARIAN_EVENT_JS" ]] && return 0