Promotions in Practice: What We Learned Exercising the State Machine
Promotions in Practice: What We Learned Exercising the State Machine
The Theory
The eight-organ system has a promotion state machine: LOCAL → CANDIDATE → PUBLIC_PROCESS → GRADUATED → ARCHIVED. Every repo starts at LOCAL. To advance, it must meet documented criteria. To be retired, it follows a formal archive process. The state machine lives in governance-rules.json, and the transitions are enforced by the promote-repo.yml workflow.
That’s the theory. Here’s what happened when we actually ran it.
What We Promoted
Four promotions across two transition types:
Two I→II promotions (Theory → Art candidates):
narratological-algorithmic-lenses: 14 narratological studies × 92 algorithms, ACTIVE status. Promoted to CANDIDATE for an interactive literary analysis experience in ORGAN-II.auto-revision-epistemic-engine: Self-governing orchestration framework with 8 phases and BLAKE3 audit chain. Promoted to CANDIDATE for an interactive governance visualization.
Two promotions to PUBLIC_PROCESS:
call-function--ontological: Ontological function-calling framework. Promoted with an essay outline: “Why AI Function Calling Needs Ontological Grounding.”classroom-rpg-aetheria: Educational RPG platform. Promoted with an existing post-mortem essay already drafted.
What We Archived
Three repos retired:
enterprise-plugin(ORGAN-III): SKELETON with INTERNAL relevance. No implementation existed, and the concept could be absorbed into existing products. Classic case of a repo that was created “just in case” and never materialized.virgil-training-overlay(ORGAN-III): LOW relevance macOS utility. Working prototype but no path to standalone product. The functionality doesn’t justify ongoing maintenance as a separate repository.announcement-templates(ORGAN-VII): INTERNAL templates consolidated into thedistribute-content.ymlworkflow. The automation replaced the need for standalone templates.
What We Learned
1. Criteria Evaluation Is Straightforward
The promotion criteria in governance-rules.json worked exactly as designed. For each promotion, we checked:
- Does the repo have documentation? (Yes/No)
- Does it have use cases? (Count them)
- Is the implementation status sufficient? (PROTOTYPE or ACTIVE for I→II)
- Are there critical alerts? (Check audit)
No ambiguity, no judgment calls on whether criteria were met. The criteria are binary, which is the point. The judgment call is whether to initiate the promotion — the criteria just verify readiness.
2. Promotions Create Obligations
This was the most important discovery. Promoting narratological-algorithmic-lenses to CANDIDATE for Art means someone needs to create art-from--narratological-algorithmic-lenses in ORGAN-II. The promotion isn’t just a status change — it’s a commitment to produce work in the destination organ.
This has calendar implications. Each I→II promotion generates an ORGAN-II task. Each promote-to-public-process generates an essay to write and publish. The state machine doesn’t just track state; it generates work.
In a team context, this would require capacity planning: don’t promote more repos than you can absorb in the destination organ. For a solo practitioner, it means being disciplined about promotion cadence.
3. Archives Are Easier Than Promotions
Every archive decision took less than a minute. The criteria are intuitive: Is the repo doing useful work? Does it have a realistic implementation path? Can its concept be absorbed elsewhere?
Compare that to promotions, which require evaluating readiness, defining the destination, and committing to follow-through. Archives close loops; promotions open them.
This suggests a healthy governance practice: archive aggressively, promote carefully. It’s better to have 60 active repos where each is progressing than 80 repos where 20 are dormant.
4. The Two-Step Problem
The state machine requires LOCAL → CANDIDATE → PUBLIC_PROCESS as two separate transitions. But for repos that already have essay content (like classroom-rpg-aetheria, which had its post-mortem drafted), the intermediate CANDIDATE state is meaningless. The repo meets PUBLIC_PROCESS criteria directly.
We executed both transitions atomically, but this revealed a design question: should there be a direct LOCAL → PUBLIC_PROCESS transition when essay content already exists?
Arguments for: reduces ceremony, matches reality. Arguments against: the CANDIDATE state is a checkpoint where someone (the human reviewer) validates readiness. Skipping it bypasses a review gate.
Our decision: keep the two-step but allow atomic execution when both criteria sets are met simultaneously. The review still happens — it just happens once instead of twice.
5. The Registry Update Is the Real Artifact
The promotion log, the criteria checks, the rationale — all of that is documentation. The actual artifact is the registry update: changing promotion_status from LOCAL to CANDIDATE and appending a note.
This is one line in a JSON file. But it’s the authoritative record that other systems (audit scripts, dashboards, workflows) read. The documentation explains why; the registry records what.
This mirrors how institutional governance works: board minutes explain deliberation, but the resolution is the binding output. The eight-organ system makes this explicit — registry-v2.json is the resolution; everything else is minutes.
6. Archiving Demonstrates Honest Governance
The most interesting reaction we anticipated from external audiences (grant reviewers, hiring managers) was about the archives. Not “why did you retire those repos?” but “you actually retire repos?”
Most portfolio systems only grow. Nobody removes old projects. The result is a portfolio that looks like a hoarder’s apartment — everything kept, nothing curated.
Formal archiving demonstrates governance maturity: the willingness to say “this didn’t work” or “this is no longer needed” is a stronger signal than maintaining the fiction that every project is active.
Three archives out of 97 repos is modest. But it establishes the pattern. Future audits will identify more candidates. The archive count will grow, and that growth will signal healthy governance, not failure.
Implications for the 90-Day Plan
The state machine exercise validates Phase 4’s premise: the governance model works in practice, not just on paper. Specific implications:
For applications (Phase 2): We can now cite specific promotions as evidence that the governance model is exercised, not just specified. “We promoted 4 repos and archived 3 through the formal state machine” is stronger than “we designed a promotion state machine.”
For content (Phase 3): Two of the four promotions generated essay obligations. These feed directly back into the ORGAN-V content pipeline — the state machine is a content generator.
For steady-state operations: The experience suggests a monthly cadence: 1-2 promotions, 1-2 archives, registry update, audit run. Sustainable, meaningful, and self-documenting.
Connection to the Eight-Organ System
This essay itself is a product of the governance it documents. The state machine exercise (ORGAN-IV) generated promotions that will produce art (ORGAN-II), essays (ORGAN-V), and potentially products (ORGAN-III). The governance isn’t separate from the creative work — it’s the mechanism that generates and coordinates it.
That’s the claim the eight-organ system makes: governance as creative infrastructure. This exercise is the first concrete evidence that the claim holds.
This essay is part of the ORGAN-V Public Process — building in public, documenting everything.
| *Related repos: orchestration-start-here | system-governance-framework* |