@rulemetric/local 0.10.0 → 0.12.0

package/dist/supabase/migrations/00193_judge_segment_pin_and_anchors.sql

@@ -0,0 +1,367 @@
+-- The judge segment gets ONE definition, and a pin outranks anything observed.
+--
+-- §6c scopes calibration to the current judge, and until now "current judge"
+-- was hand-copied into four places (00148, 00169, 00190, judge-calibration.ts)
+-- as "the most recently stamped run". Recency asks who graded LAST when the
+-- question is whose bias we can CORRECT, and the two come apart the instant a
+-- stray run lands. Measured 2026-08-18 on the one evolve-enrolled target:
+--
+--     claude-opus-5[1m]          355 runs   Jul 30 - Aug 13
+--     claude-opus-4-8[1m]        303 runs   Jul 20 - Jul 29   <- all 37 labels
+--     (unstamped)                159 runs   Mar 25 - Aug 17
+--     claude-fable-5             113 runs   Aug 08 - Aug 14
+--     claude-haiku-4-5            80 runs   Aug 14 - Aug 16   <- elected, 0 labels
+--
+-- Recency elected the segment with zero anchors, so the adequacy gate reported
+-- `0/50 human-labeled runs` and asked for fifty more while thirty-seven sat one
+-- segment away. 00148's grader pin then pinned the NEXT batch to that same
+-- stray, making the drift self-reinforcing; #357 quarantined fallback runs from
+-- electing, but a run the producer never pinned has nothing to fall back FROM,
+-- so unpinned evolution batches walked straight through the quarantine.
+--
+-- Three tiers, descending authority:
+--   1. PIN      metadata.graderModel — a decision a person made. Nothing
+--               observed in the run table may overrule it. A pinned segment
+--               with zero runs is a correct answer: grading starts there.
+--   2. ANCHORS  the segment holding the most fully human-labeled runs — the
+--               only segment that can produce a corrected estimate at all.
+--   3. RECENCY  the old rule, surviving as the tie-break and the
+--               no-anchors-anywhere fallback.
+--
+-- Fallback runs (stamped != requested) are quarantined from ELECTING but still
+-- count as data, exactly as #357 established. If every stamped run fell back,
+-- the whole stamped set votes rather than electing nothing — an empty segment
+-- would silently drop every LLM-graded run.
+--
+-- apps/api/src/lib/judge-calibration.ts `electJudgeSegment()` implements the
+-- same three tiers for the TypeScript readers, and its unit tests pin the tier
+-- order. Change one side without the other and the scheduled path will measure
+-- a different segment than the reviewed path.
+-- ---------------------------------------------------------------------------
+
+create or replace function public.eval_target_judge_segment(p_target_id uuid)
+returns text
+language sql
+stable
+security definer
+set search_path = public
+as $$
+  with elector as (
+    select
+      r.grading->>'judge_model' as model,
+      r.created_at,
+      (
+        r.grading->>'judge_model_requested' is null
+        or r.grading->>'judge_model_requested' = r.grading->>'judge_model'
+      ) as clean,
+      -- Guarded: a grading blob whose expectations is not an array would make
+      -- jsonb_array_elements raise, and one malformed run must not take the
+      -- whole election down.
+      case
+        when jsonb_typeof(r.grading->'expectations') = 'array' then (
+          select count(*)
+          from jsonb_array_elements(r.grading->'expectations') e
+          where coalesce(e->>'method', 'llm') = 'llm'
+            and coalesce(e->>'errored', 'false') <> 'true'
+        )
+        else 0
+      end as llm_total,
+      coalesce(a.llm_annotated, 0) as llm_annotated
+    from eval_runs r
+    left join (
+      select eval_run_id, count(*) filter (where judge_method = 'llm') as llm_annotated
+      from eval_grade_annotations
+      where eval_target_id = p_target_id
+      group by eval_run_id
+    ) a on a.eval_run_id = r.id
+    where r.eval_target_id = p_target_id
+      and r.status = 'completed'
+      and r.configuration in ('with_target', 'without_target')
+      and r.grading->>'judge_model' is not null
+  ),
+  has_clean as (
+    select exists (select 1 from elector where clean) as v
+  ),
+  electorate as (
+    select e.* from elector e, has_clean h where e.clean or not h.v
+  ),
+  pin as (
+    select nullif(btrim(t.metadata->>'graderModel'), '') as model
+    from eval_targets t
+    where t.id = p_target_id
+  ),
+  anchors as (
+    -- Ties broken by recency then model string: a tie-break that fell through
+    -- to nothing would leave the segment depending on row order, which is the
+    -- same instability recency had.
+    select model
+    from electorate
+    where llm_total > 0 and llm_annotated >= llm_total
+    group by model
+    order by count(*) desc, max(created_at) desc, model desc
+    limit 1
+  ),
+  recency as (
+    select model from electorate order by created_at desc, model desc limit 1
+  )
+  select coalesce(
+    (select model from pin),
+    (select model from anchors),
+    (select model from recency)
+  );
+$$;
+
+comment on function public.eval_target_judge_segment(uuid) is
+  'Canonical §6c judge segment for an eval target: metadata.graderModel pin, else the segment holding the most fully human-labeled runs, else the most recently stamped run. Fallback-graded runs (stamped <> requested) cannot elect. Mirrors electJudgeSegment() in apps/api/src/lib/judge-calibration.ts — the two must not diverge. Never re-derive this inline: the hand-copied recency rule lived in four places and elected a zero-anchor segment for four days (2026-08-18).';
+
+-- ---------------------------------------------------------------------------
+-- Both producers now ask the function instead of carrying their own copy.
+-- ---------------------------------------------------------------------------
+
+create or replace function public.enqueue_eval_autorun()
+returns integer
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+  queued integer;
+begin
+  with eligible as (
+    select t.id, t.user_id,
+      -- Canonical segment (00193). Was an inline "most recent stamped run"
+      -- subquery, which is how a credit-exhaustion fallback became the pin.
+      public.eval_target_judge_segment(t.id) as current_judge
+    from eval_targets t
+    where coalesce(t.metadata->>'autoRunEnabled', 'false') = 'true'
+      -- Gate 0 (00190): the target must be anchored to something a promotion
+      -- could land on. Without this, a batch is two LLM executions plus a
+      -- judged grade spent to rewrite a row nothing reads.
+      and (
+        t.instruction_id is not null
+        or t.project_path is not null
+        or t.name like '/%'
+      )
+      -- Gate 2a: recent grading wasn't MOSTLY ungradeable (proportional, and
+      -- identical to the evolution producer's 2a since 00163).
+      and not exists (
+        select 1 from eval_runs r
+        where r.eval_target_id = t.id
+          and r.created_at > now() - interval '7 days'
+        group by r.eval_target_id
+        having count(*) >= 5
+           and count(*) filter (
+                 where jsonb_typeof(r.grading->'expectations') = 'array'
+                   and exists (
+                     select 1 from jsonb_array_elements(r.grading->'expectations') e
+                     where coalesce(e->>'errored', 'false') = 'true'
+                   )
+               ) * 4 >= count(*)
+      )
+      -- Gate 2b: no human anchors pointing at an ungradeable assertion.
+      and not exists (
+        select 1
+        from eval_grade_annotations a
+        join eval_runs r on r.id = a.eval_run_id
+        where a.eval_target_id = t.id
+          and jsonb_typeof(r.grading->'expectations') = 'array'
+          and coalesce(
+            r.grading->'expectations'->(a.expectation_index)->>'errored', 'false'
+          ) = 'true'
+      )
+      -- Gate 2c: last week's batch wasn't mostly failures.
+      and not exists (
+        select 1 from eval_runs r
+        where r.eval_target_id = t.id
+          and r.created_at > now() - interval '7 days'
+        group by r.eval_target_id
+        having count(*) >= 5
+           and count(*) filter (where r.status = 'failed') * 4 >= count(*)
+      )
+      -- Gate 3: the target has live cases to actually run.
+      and exists (
+        select 1 from evals ev
+        where ev.eval_target_id = t.id and ev.retired_at is null
+      )
+      -- One in flight at a time, per the 00083/00086 pattern.
+      and not exists (
+        select 1 from agent_jobs j
+        where j.task_kind = 'cron_eval_autorun'
+          and j.status in ('pending', 'claimed', 'running')
+          and j.payload->>'evalTargetId' = t.id::text
+      )
+  ), ins as (
+    insert into agent_jobs (user_id, task_kind, status, payload, dedupe_key)
+    select e.user_id,
+           'cron_eval_autorun',
+           'pending',
+           jsonb_build_object('evalTargetId', e.id::text, 'maxRuns', 12)
+             || case
+                  when e.current_judge is not null
+                    then jsonb_build_object('graderModel', e.current_judge)
+                  else '{}'::jsonb
+                end,
+           'eval-autorun:' || e.id::text
+    from eligible e
+    returning 1
+  )
+  select count(*)::int into queued from ins;
+
+  return queued;
+end;
+$$;
+
+comment on function public.enqueue_eval_autorun() is
+  'Nightly producer for cron_eval_autorun. Enqueues one bounded depth batch per OPTED-IN, ANCHORED, healthy, under-powered eval target, with the grader pinned to the target''s canonical judge segment (public.eval_target_judge_segment, 00193 — pin > anchors > recency; was an inline recency subquery from 00148/#196). Gate 0 (00190) requires instruction_id, project_path, or an absolute-path name. Health 2a is PROPORTIONAL as of 00169. Opt in with: update eval_targets set metadata = coalesce(metadata, ''{}''::jsonb) || ''{"autoRunEnabled":true}''::jsonb where id = ...';
+
+-- ---------------------------------------------------------------------------
+-- The evolution producer never pinned a grader AT ALL.
+--
+-- 00148 pinned the autorun batch precisely so a scheduled run could not fork
+-- the segment. The evolution producer — which spends far more per night, and
+-- whose paired replays are the ONLY route to a promotion (§13, Mode A) — was
+-- never given the same treatment. Its runs therefore carried no
+-- `judge_model_requested`, so #357's fallback quarantine had nothing to compare
+-- against and they elected freely. Unpinned evolution batches are how
+-- claude-haiku-4-5 took the segment on 2026-08-14.
+--
+-- Function is otherwise byte-identical to 00183.
+-- ---------------------------------------------------------------------------
+
+create or replace function public.enqueue_instruction_evolution()
+returns integer
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+  queued integer;
+begin
+  with health_ok as (
+    -- The gates SHARED by both enrolment paths, evaluated once. All copied
+    -- byte-identical from the live definition (00163's revision): pause,
+    -- proportional 2a, absolute 2b, proportional 2c, live cases, change
+    -- budget, one-in-flight.
+    select t.id, t.user_id
+    from eval_targets t
+    where coalesce(t.metadata->>'autoEvolvePaused', 'false') <> 'true'
+      -- Health 2a: recent grading wasn't MOSTLY ungradeable (proportional, 00163).
+      and not exists (
+        select 1 from eval_runs r
+        where r.eval_target_id = t.id
+          and r.created_at > now() - interval '7 days'
+        group by r.eval_target_id
+        having count(*) >= 5
+           and count(*) filter (
+                 where jsonb_typeof(r.grading->'expectations') = 'array'
+                   and exists (
+                     select 1 from jsonb_array_elements(r.grading->'expectations') e
+                     where coalesce(e->>'errored', 'false') = 'true'
+                   )
+               ) * 4 >= count(*)
+      )
+      -- Health 2b: no human anchors pointing at an ungradeable assertion (absolute).
+      and not exists (
+        select 1
+        from eval_grade_annotations a
+        join eval_runs r on r.id = a.eval_run_id
+        where a.eval_target_id = t.id
+          and jsonb_typeof(r.grading->'expectations') = 'array'
+          and coalesce(
+            r.grading->'expectations'->(a.expectation_index)->>'errored', 'false'
+          ) = 'true'
+      )
+      -- Health 2c: last week's batch wasn't mostly failures.
+      and not exists (
+        select 1 from eval_runs r
+        where r.eval_target_id = t.id
+          and r.created_at > now() - interval '7 days'
+        group by r.eval_target_id
+        having count(*) >= 5
+           and count(*) filter (where r.status = 'failed') * 4 >= count(*)
+      )
+      -- Live cases to measure against — at least MIN_LIVE_CASES (3).
+      -- `exists` (>= 1) was the bug: see 00183's header.
+      and (
+        select count(*) from evals ev
+        where ev.eval_target_id = t.id and ev.retired_at is null
+      ) >= 3
+      -- Change budget (cheap exclusion; the API is the authority).
+      and (
+        select count(*)
+        from instruction_promotions p
+        where p.eval_target_id = t.id
+          and p.applied
+          and p.created_at > now() - interval '7 days'
+      ) < 3
+      -- One in flight at a time.
+      and not exists (
+        select 1 from agent_jobs j
+        where j.task_kind = 'cron_instruction_evolution'
+          and j.status in ('pending', 'claimed', 'running')
+          and j.payload->>'evalTargetId' = t.id::text
+      )
+  ),
+  manual as (
+    -- The hand-picked path, unchanged and uncapped.
+    select h.id, h.user_id
+    from health_ok h
+    join eval_targets t on t.id = h.id
+    where coalesce(t.metadata->>'autoEvolveEnabled', 'false') = 'true'
+  ),
+  auto_ranked as (
+    -- The stated rule. Round-robin: never-decided first (nulls first), then
+    -- least-recently-decided, so the cap rotates through the candidate pool
+    -- instead of re-measuring the same winners nightly.
+    select h.id, h.user_id,
+           row_number() over (
+             partition by h.user_id
+             order by (
+               select max(p.created_at)
+               from instruction_promotions p
+               where p.eval_target_id = h.id
+             ) asc nulls first,
+             h.id
+           ) as rn
+    from health_ok h
+    join eval_targets t on t.id = h.id
+    where t.type = 'instruction'
+      and coalesce(t.metadata->>'autoEvolveOptOut', 'false') <> 'true'
+      -- Not already covered by the manual path.
+      and coalesce(t.metadata->>'autoEvolveEnabled', 'false') <> 'true'
+      -- ACTIVE (00145's load-bearing gate): a run in the last 30 days.
+      and exists (
+        select 1 from eval_runs r
+        where r.eval_target_id = t.id
+          and r.created_at > now() - interval '30 days'
+      )
+  ),
+  eligible as (
+    select id, user_id from manual
+    union
+    select id, user_id from auto_ranked where rn <= 3
+  ),
+  ins as (
+    insert into agent_jobs (user_id, task_kind, status, payload, dedupe_key)
+    select e.user_id,
+           'cron_instruction_evolution',
+           'pending',
+           jsonb_build_object('evalTargetId', e.id::text)
+             || case
+                  when public.eval_target_judge_segment(e.id) is not null
+                    then jsonb_build_object(
+                           'graderModel', public.eval_target_judge_segment(e.id))
+                  else '{}'::jsonb
+                end,
+           'instruction-evolution:' || e.id::text
+    from eligible e
+    returning 1
+  )
+  select count(*)::int into queued from ins;
+
+  return queued;
+end;
+$$;
+
+comment on function public.enqueue_instruction_evolution() is
+  'Nightly producer for cron_instruction_evolution. Two enrolment paths as of 00166: MANUAL (autoEvolveEnabled=true, uncapped) and the STATED RULE (type=instruction, not opted out via autoEvolveOptOut, an eval run in 30 days, capped at 3/user/night round-robin by least-recent decision). Both share the health gates (2a proportional per 00163, 2b absolute, 2c proportional), live-cases (>= 3 per 00183), change-budget and one-in-flight guards. As of 00193 the payload PINS graderModel to the canonical judge segment — without it the paired replays carried no judge_model_requested, so #357''s fallback quarantine could not see them and they forked the segment freely. Auto-enrolled cycles are measure-only: writing still requires autoEvolveApply AND an explicit immutableSections.';

package/dist/supabase/migrations/00194_refine_cases_producer.sql

@@ -0,0 +1,91 @@
+-- An actuator for the refusal the loop had been printing every night.
+--
+-- `cron_instruction_evolution` has been ending in `{"skipped":"not-adequate"}`
+-- with the reason "3/5 cases do not discriminate with vs without — cull or
+-- replace them before adding runs; more runs of a non-discriminating case
+-- cannot lower the MDE; MDE ±49pp exceeds the ±20pp target effect" on every
+-- night measured (2026-08-16, -17, -18). The remedy shipped in 2026-07 as
+-- `rulemetric evals refine-cases <id> --yes` — a command a human types. So the
+-- nightly loop diagnosed its own blocker correctly, spent a two-arm replay
+-- proving it, and had no way to act.
+--
+-- Slot: 05:30, inside the existing nightly chain and deliberately BEFORE the
+-- 06:10 autorun batch, so replacements generated tonight start collecting depth
+-- tonight rather than waiting a day:
+--
+--     04:30 suggestions -> 04:45 training -> 05:00 auto-accept
+--       -> 05:30 REFINE  -> 06:10 autorun  -> 07:30 evolution
+--
+-- Opt-in per target (metadata.autoRefineCases), matching autoEvolveEnabled:
+-- refinement rewrites what a target MEASURES, and a measurement apparatus that
+-- reshapes itself without consent cannot then be trusted to report on itself.
+-- The handler re-reads consent when it claims the job, so revoking it stops an
+-- already-queued run.
+-- ---------------------------------------------------------------------------
+
+create or replace function public.enqueue_refine_cases()
+returns integer
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+  queued integer;
+begin
+  with eligible as (
+    select t.id, t.user_id
+    from eval_targets t
+    where coalesce(t.metadata->>'autoRefineCases', 'false') = 'true'
+      -- Discrimination is a CROSS-COHORT quantity: without runs in both arms
+      -- there is nothing to diagnose, and the handler would spend an API round
+      -- trip to say so. Cheap pre-filter, same answer.
+      and exists (
+        select 1 from eval_runs r
+        where r.eval_target_id = t.id
+          and r.status = 'completed'
+          and r.configuration = 'with_target'
+      )
+      and exists (
+        select 1 from eval_runs r
+        where r.eval_target_id = t.id
+          and r.status = 'completed'
+          and r.configuration = 'without_target'
+      )
+      -- There must be something left to measure with. A target already at the
+      -- floor cannot afford a retirement, and the handler refuses anyway —
+      -- but not enqueuing it keeps the refusal out of the nightly feed.
+      and (
+        select count(*) from evals ev
+        where ev.eval_target_id = t.id and ev.retired_at is null
+      ) >= 1
+      -- One in flight at a time, per the 00083/00086 pattern.
+      and not exists (
+        select 1 from agent_jobs j
+        where j.task_kind = 'cron_refine_cases'
+          and j.status in ('pending', 'claimed', 'running')
+          and j.payload->>'evalTargetId' = t.id::text
+      )
+  ), ins as (
+    insert into agent_jobs (user_id, task_kind, status, payload, dedupe_key)
+    select e.user_id,
+           'cron_refine_cases',
+           'pending',
+           jsonb_build_object('evalTargetId', e.id::text),
+           'refine-cases:' || e.id::text
+    from eligible e
+    returning 1
+  )
+  select count(*)::int into queued from ins;
+
+  return queued;
+end;
+$$;
+
+comment on function public.enqueue_refine_cases() is
+  'Nightly producer for cron_refine_cases (§6e). Enqueues one refinement per OPTED-IN target (metadata.autoRefineCases=true) that has completed runs in BOTH cohorts and at least one live case. Retires cases carrying no treatment signal and regenerates replacements — the actuator for the "N/M cases do not discriminate" refusal the evolution loop printed nightly with no way to act on it. Runs at 05:30, before the 06:10 autorun slot, so tonight''s replacements collect depth tonight. Opt in with: update eval_targets set metadata = coalesce(metadata, ''{}''::jsonb) || ''{"autoRefineCases":true}''::jsonb where id = ...';
+
+select cron.schedule(
+  'enqueue_refine_cases',
+  '30 5 * * *',
+  $$select public.enqueue_refine_cases();$$
+);

package/dist/supabase/migrations/00195_skill_usage_views.sql

@@ -0,0 +1,109 @@
+-- Skills were being USED and the product could not see it.
+--
+-- Measured 2026-08-18: `session_events` holds 158 `Skill` tool invocations over
+-- 30 days, most recent that day, with the skill name sitting in plain sight at
+-- `tool_input->>'skill'`. Meanwhile `session_instructions` held 0 rows for any
+-- skill, `treatment_exposures` had no `skill` type at all, and of 6,086 skill
+-- instructions 0 had ever been accepted and 0 archived. The signal was captured
+-- and dropped on the floor.
+--
+-- That gap is why the loop has never proposed retiring a skill: grooming
+-- reasons over measured effect, and there was no measurement to reason over.
+--
+-- ## Views, not a table
+--
+-- The obvious shape is a `skill_invocations` table written at ingest. It is the
+-- wrong one here: the event side-effects already exist in TWO mirrored copies
+-- (`routes/sessions/ingest/events.ts` and `lib/ingest-batcher.ts`), and a third
+-- dual-write would be a third thing to keep in sync — plus a backfill to get
+-- wrong. A view over the events cannot drift from its source, needs no
+-- backfill, and is correct for all history the moment it exists.
+--
+-- ## Why this is a stronger signal than anything already recorded
+--
+-- Every existing `session_instructions.link_method` — project_match,
+-- context_file, auto_capture, manual — means the instruction was PRESENT in
+-- context. A Skill invocation means it was USED. §12 spends its length on the
+-- gap between exposure and effect; this is the first record on the right side
+-- of that gap, and it is worth keeping distinct from presence rather than
+-- folding into it.
+-- ---------------------------------------------------------------------------
+
+-- Skill events are a rounding error in session_events (158 of ~30k), so a
+-- partial index keeps the scan proportional to what is actually read.
+create index if not exists idx_session_events_skill_tool
+  on public.session_events (session_id, timestamp)
+  where tool_name = 'Skill';
+
+-- Catalog skills are named `<source-repo>--<skill>`; invocations carry either
+-- the bare `<skill>` or `<plugin>:<skill>`. Matching on the leaf therefore
+-- needs the leaf to be indexable — a `like '%--' || name` predicate cannot use
+-- an index at all, and there are 6,086 skill rows to scan without one.
+create index if not exists idx_instructions_skill_leaf
+  on public.instructions ((split_part(name, '--', 2)))
+  where type = 'skill';
+
+-- ---------------------------------------------------------------------------
+-- Raw invocations, parsed.
+-- ---------------------------------------------------------------------------
+create or replace view public.skill_invocations as
+select
+  e.session_id,
+  e.timestamp                                   as invoked_at,
+  e.tool_input->>'skill'                        as raw_name,
+  -- `plugin:skill` is one namespace form Claude Code emits; a bare name is the
+  -- other. Splitting rather than storing the raw string keeps the join below
+  -- honest about which half is the identity.
+  nullif(split_part(e.tool_input->>'skill', ':', 1), e.tool_input->>'skill')
+                                                as plugin,
+  case
+    when position(':' in e.tool_input->>'skill') > 0
+      then split_part(e.tool_input->>'skill', ':', 2)
+    else e.tool_input->>'skill'
+  end                                           as skill_name
+from public.session_events e
+where e.tool_name = 'Skill'
+  and e.tool_input->>'skill' is not null
+  and e.tool_input->>'skill' <> '';
+
+comment on view public.skill_invocations is
+  'Every Skill tool invocation, parsed out of session_events. A view rather than a table: the event side-effects already exist in two mirrored copies and a third dual-write would be a third thing to keep in sync. Names arrive as `<skill>` or `<plugin>:<skill>`.';
+
+-- ---------------------------------------------------------------------------
+-- Invocations resolved to the catalog, WITHOUT discarding the unresolved ones.
+--
+-- Measured 2026-08-18: only 11 of 81 distinct invoked skills exist in the
+-- instructions catalog. The other 70 are the user's own local skills
+-- (`git-ship`, `commit`, `publish`, `auto-deploy`) — the ones actually used
+-- every day, and the ones a catalog-only join would silently drop. An inner
+-- join here would have reported 14% of reality and looked complete.
+--
+-- `instruction_id` is therefore NULLABLE and null means "used but not in the
+-- catalog", which is a finding, not a failure.
+-- ---------------------------------------------------------------------------
+create or replace view public.skill_usage as
+select
+  si.session_id,
+  si.invoked_at,
+  si.raw_name,
+  si.plugin,
+  si.skill_name,
+  s.user_id,
+  s.project_id,
+  s.project_path,
+  m.instruction_id
+from public.skill_invocations si
+join public.sessions s on s.id = si.session_id
+left join lateral (
+  select i.id as instruction_id
+  from public.instructions i
+  where i.type = 'skill'
+    and (i.name = si.skill_name or split_part(i.name, '--', 2) = si.skill_name)
+  -- Exact name beats a leaf match, so a skill whose full name happens to equal
+  -- another's leaf cannot steal the attribution.
+  order by (i.name = si.skill_name) desc, i.id
+  limit 1
+) m on true;
+
+comment on view public.skill_usage is
+  'Skill invocations joined to the session that ran them and, where one exists, the catalog instruction. instruction_id is NULL for skills used but not catalogued — measured 2026-08-18, that was 70 of 81 distinct skills, so an inner join here would report 14% of reality.';

package/dist/supabase/migrations/00196_retire_unused_skills_producer.sql

@@ -0,0 +1,102 @@
+-- The loop's first unattended REMOVAL.
+--
+-- Everything the loop has actuated until now has added: a rule appended to
+-- CLAUDE.md, a skill installed, a hook registered, an instruction promoted.
+-- Grooming's stated contract was that removals are surfaced for human review
+-- and NEVER auto-archived, and this producer deliberately changes that for one
+-- narrow case (owner's decision, 2026-08-18). Recording the change here so the
+-- next reader finds the departure rather than inferring it.
+--
+-- What makes it narrow:
+--
+--   * ONLY skills, and only ones with ZERO recorded invocations since install.
+--     "Invoked but measures unhelpful" is an observational estimate and stays a
+--     proposal, exactly as measured-harmful rules do. An absence of use is a
+--     fact; an absence of benefit is an inference.
+--   * ONLY skills the loop itself installed, evidenced by a
+--     `recommendation_applications` row with status='applied'. The handler
+--     re-checks this; the API is the authority.
+--   * ONLY while skill capture is demonstrably live. A dark Skill channel makes
+--     every skill look unused, and the first quiet fortnight would otherwise
+--     read as "retire everything". Judged by `loadUnusedSkillCandidates`.
+--   * A per-run cap in the handler, and a backup written before every delete
+--     (`applyRetraction`) because an untracked skill file has no other copy and
+--     git cannot restore it.
+--
+-- Slot: 05:45, after auto-accept (05:00) and refine (05:30), before the autorun
+-- batch (06:10). Adding and removing in the same nightly pass, in that order,
+-- means a skill adopted tonight is never a retirement candidate tonight — it
+-- has to survive the unused window first.
+--
+--     04:30 suggestions -> 04:45 training -> 05:00 auto-accept
+--       -> 05:30 refine -> 05:45 RETIRE   -> 06:10 autorun -> 07:30 evolution
+--
+-- Opt-in per project (metadata.autoRetireSkills). Nothing is retired for a user
+-- who has not asked for it, and the handler cannot be reached without a job.
+-- ---------------------------------------------------------------------------
+
+create or replace function public.enqueue_retire_unused_skills()
+returns integer
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+  queued integer;
+begin
+  with eligible as (
+    -- The canonical checkout comes from the VIEW, never re-derived: is_worktree
+    -- is rewritten from each session's own metadata on every ingest, so a
+    -- hand-rolled ranking elects a path nobody works in (00186).
+    select pr.created_by as user_id, p.path as canonical_path
+    from public.project_canonical_checkouts p
+    join public.projects pr on pr.id = p.project_id
+    where coalesce(pr.metadata->'autoRetireSkills'->>'enabled', 'false') = 'true'
+      -- Cheap pre-filter: a user with no skill invocations captured at all has
+      -- a dark channel, and the handler would refuse anyway. Not enqueuing it
+      -- keeps a guaranteed refusal out of the nightly feed.
+      and exists (
+        select 1 from public.skill_usage su
+        where su.user_id = pr.created_by
+          and su.invoked_at > now() - interval '14 days'
+      )
+      -- There must be something that could plausibly be retired: at least one
+      -- of the user's own skills old enough to have had a fair chance.
+      and exists (
+        select 1 from public.instructions i
+        where i.created_by = pr.created_by
+          and i.type = 'skill'
+          and i.archived = false
+          and i.created_at < now() - interval '30 days'
+      )
+      -- One in flight at a time, per the 00083/00086 pattern.
+      and not exists (
+        select 1 from public.agent_jobs j
+        where j.task_kind = 'cron_retire_unused_skills'
+          and j.status in ('pending', 'claimed', 'running')
+          and j.payload->>'projectPath' = p.path
+      )
+  ), ins as (
+    insert into agent_jobs (user_id, task_kind, status, payload, dedupe_key)
+    select e.user_id,
+           'cron_retire_unused_skills',
+           'pending',
+           jsonb_build_object('projectPath', e.canonical_path),
+           'retire-unused-skills:' || e.canonical_path
+    from eligible e
+    returning 1
+  )
+  select count(*)::int into queued from ins;
+
+  return queued;
+end;
+$$;
+
+comment on function public.enqueue_retire_unused_skills() is
+  'Nightly producer for cron_retire_unused_skills (05:45). Enqueues one run per OPTED-IN project (projects.metadata.autoRetireSkills.enabled=true) whose user has live skill capture and at least one own skill older than the unused window. The loop''s first unattended REMOVAL: only skills, only never-invoked ones, only ones the loop itself installed, only while skill capture is live, capped per run, and with a backup written before every delete. Used-but-unhelpful skills remain proposals. Opt in with: update projects set metadata = coalesce(metadata, ''{}''::jsonb) || ''{"autoRetireSkills":{"enabled":true}}''::jsonb where id = ...';
+
+select cron.schedule(
+  'enqueue_retire_unused_skills',
+  '45 5 * * *',
+  $$select public.enqueue_retire_unused_skills();$$
+);