Skip to content
PETROVA

2026-05-10 — Phase transitions derived from decision-doc history; KAHN placeholder retired

Date: 2026-05-10 Status: closed Supersedes: none Superseded-by: none — current

Context

Section titled “Context”

/console/repo/<slug> had a “Recent transitions” panel that called petrova.transitions.recent, which dispatched to KahnSource pointed at https://kahn.example.com. The endpoint never existed; the panel rendered empty for every slug. The plan in docs/superpowers/plans/2026-05-10-state-freshness.md (Phase 6b) proposed a consumer-side push action with HMAC + an /emit endpoint and a JSONL-backed state file — three new moving parts to surface what is, in practice, already encoded in each repo’s docs/decisions/phase-N-(open|close|complete).md history.

Decision

Section titled “Decision”

Replace KahnSource with TransitionsSource, backed by state/transitions/<slug>.jsonl files written by the existing petrova sweep-state cron. Each line is one synthesized event: {slug, from, to, at, note} derived from a phase decision doc. The host’s petrova.transitions.recent reads those JSONLs; the dashboard panel finally populates with no consumer-repo work required.

Alternatives considered

Section titled “Alternatives considered”
  • Build the push side as planned (HMAC + /emit + per-repo Action). Rejected for v1: more infra surface (function endpoint, secret rotation, replay protection) for the same data we already pull every 6 hours. Push-side optionality stays open if/when sub-cron-tick latency matters.
  • Keep KahnSource and stand up a real Kahn endpoint. Rejected: KAHN as originally framed (loop-convergence run history) is a different signal from phase transitions, and there is no consumer of that signal yet. Renaming-as-rebuild on the existing surface is the lower-friction move.

Consequences

Section titled “Consequences”

For code:

  • host/src/sources/kahn.ts deleted; host/src/sources/transitions.ts added.
  • ToolContext.kahn removed; ToolContext.transitions added.
  • PETROVA_HOST_KAHN_API env var no longer required by loadShardConfig.
  • cli/src/verbs/sweep_state.ts writes state/transitions/<slug>.jsonl alongside state/<slug>.yaml.
  • Dashboard repo-detail “Recent transitions” panel now renders real data after the next sweep + redeploy.

For docs:

  • This doc.
  • Plan docs/superpowers/plans/2026-05-10-state-freshness.md Sub-phase 6b is satisfied by the pull-derivation approach; the push-side variant is parked.

For in-flight phases:

  • None.

For invariants:

  • No MR-N changes.

References

Section titled “References”
  • Plan: docs/superpowers/plans/2026-05-10-state-freshness.md
  • Sweep verb: cli/src/verbs/sweep_state.ts
  • New source: host/src/sources/transitions.ts

Sign-off

Section titled “Sign-off”
  • Subagent: Claude Code (main direct-push under standing approval)
  • Human: alex@devarno.com — 2026-05-10