tkersey/universalist

Universalist

Universalist synthesizes context-relative, correct-by-construction boundary architecture. In Actuating composition it nominates a candidate; Actuating alone adjudicates and authors the Construction.

It uses category theory as a hidden optimizer to derive the smallest effective boundary artifact whose representation, constructors, eliminators, compositions, and interpretations enforce the current context's requirements. It makes invalid states and illegal compositions unrepresentable where the host permits; centralizes unavoidable runtime validation at explicit owners; preserves required observations and compatibility; records residual obligations and invalidation triggers; and returns an obstruction rather than inventing correctness the context cannot justify.

Default discipline:

one owned boundary
one current context
one architectural axis
one typed hole
one smallest effective artifact
one owner for every residual check
one law and one falsifier

Category theory must change what the architecture owns, permits, excludes, composes, observes, preserves, identifies, generates, interprets, proves, or refuses to invent. Otherwise it is explanatory metadata.

Boundary-trigger mandate

Use this skill whenever implementation, refactoring, review, migration, or resolution considers a code boundary. A boundary is considered when work creates, changes, preserves, validates, migrates, bypasses, removes, or repairs how values, effects, state, evidence, authority, or behavior cross owners or representations.

Examples include module and package APIs, public/internal contracts, DTOs and schemas, parsers and validators, storage and wire formats, syntax and interpreters, effect handlers, protocols, plugins, tools, CLIs, processes, repositories, and deployment surfaces.

Activation is broad; escalation is narrow. An already exact boundary may be preserved. A local edit wholly inside one unchanged boundary does not trigger this skill.

Trigger-to-evidence kernel

Record the compact boundary disposition immediately:

Boundary:
Disposition: preserved / introduced / changed / repaired / removed / bypass-justified
Disposition rationale and evidence:
Owner:
Source / target:
Current requirements:
Required observations and compatibility:
Preserved / forgotten / generated / observed:
Law:
Falsifier:
Residual obligations:
Invalidation triggers:

Then:

1. Decide whether the route is consequential under Decision observability: at least two plausible routes materially differ in persistent behavior, authority, compatibility, migration, enforcement, invalidation, or proof obligations.
2. For a consequential route, complete the current-context, comparison, Boundary Artifact Contract, enforcement, residual, invalidation, law, and falsifier analysis before mutation. In Actuating composition, hand this nomination directly to Actuating; the Construction is the decision carrier.
3. Allocate a plan and emit one root SDR-v1 only when Decision durability requires an independently addressable Universalist decision.
4. For a routine or uncontested seam, retain the compact disposition and continue the repository's ordinary workflow.

Decision durability

Materiality controls reasoning depth; durability controls whether that reasoning needs a separate plan and receipt.

Independent durability exists when no current Actuating Construction will carry the complete decision and the user requests a durable record, or standalone, cross-session, multi-actor, migration, or supersession work must later address the Universalist decision directly.

When an Actuating Construction carries the nomination, adjudication, proof, and retirement obligations, do not allocate a Universalist plan or emit SDR-v1 merely because the boundary choice is consequential. Session evidence and the Construction remain inspectable without a duplicate decision artifact.

Execution-time reclassification gate

Treat a compact disposition, Actuating-bound nomination, or plan-bound decision as a proof lease. Whenever new execution evidence may materially change the owner, requirements, observations, compatibility, effects, resources, axis, typed hole, law, falsifier, enforcement, residuals, invalidators, route, or seam decomposition, reclassify before the next affected mutation.

Record:

Prior disposition or decision:
New evidence:
Material semantic delta:
Outcome: retain / split / escalate / obstruct
Invalidated artifacts: receipt / plan / proof lease / none
Successor packets: owner + axis + seam / none

• retain — the same owner, axis, law, falsifier, route, and obligations still govern;
• split — independent owners or axes have appeared; create one packet per independently governed seam;
• escalate — the route materially changed; stop before mutation and repeat the full analysis;
• obstruct — no honest current route is representable or authorized.

Before Actuating selects a Construction, revise the nomination in place. After Actuating materializes a Construction, return material evidence to Actuating for retain, successor, or obstruction; Universalist must not reopen it. Once an SDR-v1 exists, do not overwrite it. Evidence discovered only after an affected mutation is a proof failure; re-establish the lease before further mutation.

Diff size, retry count, test count, elapsed time, and categorical vocabulary do not establish materiality by themselves.

Current-context contract

Correctness is always relative to an attributed context Γ. Before claiming that an artifact is correct by construction, record:

Context identifier or evidence fingerprint:
Requirement sources:
Required observations:
Equivalence / normalization:
Authority and policy:
Compatibility and migration constraints:
Effects and ordering:
Resource constraints:
Host enforcement capabilities:
Freshness / validity horizon:

The host capability inventory must say what can actually be enforced by:

type or data representation
module opacity / private constructors
generated code or exhaustive matching
lawful composition API
interpreter / handler ownership
database or schema constraints
runtime validation
monitoring / audit / invalidation

Do not claim static enforcement where the language, module system, persistence layer, deployment topology, or external authority cannot provide it.

Smallest effective artifact

State the ordinary candidate first: record, tagged union, checked constructor, adapter, explicit parameter, state machine, operation IR, handler, labelled graph, query, bounded loop, canonical merge, or one typed compatibility witness.

Define the comparison universe before calling anything smallest or canonical:

admissible artifacts
admissible transformations
sanctioned observations
equivalence / normalization
compatibility
authority
effects and ordering
resources
host capabilities

“Smallest” means minimal in this universe relative to requirements and resources. It does not mean shortest code or the simplest category-theory name.

A candidate dominates another only with evidence that it preserves required observations while reducing invalid representable states, illegal public compositions, unchecked construction paths, duplicated authority, runtime proof burden, information loss, migration risk, or resource cost.

If several candidates are incomparable minima, the result is underdetermined. Do not manufacture a winner.

One axis and one typed hole

Analyze one architectural axis and one compatible hole per packet:

axes:
  data shape
  syntax-semantics
  behavior
  base composition
  two-dimensional composition
  description composition
  context action
  locality
  schema-context
  transport-realization
  presentation
  proof

holes:
  object
  map
  interpreter
  composition
  representation
  equivalence
  locality
  context action
  square
  proof

Independent pressures become linked packets. Double-category squares, Day convolution, Tambara framing, effect ordering, locality, data shape, and context preparation may coexist; they do not compete as one global winner.

Double-category architecture

Use the two_dimensional_composition card when two semantically different arrow families both compose and correctness depends on typed squares relating them.

horizontal arrows
  processes, open systems, queries, generalized interactions, executable behavior

vertical arrows
  migrations, refinements, strict maps, reindexings, deployments, architecture changes

squares
  compatibility witnesses whose four boundaries are explicit

The architectural maxim is:

Processes compose horizontally.
Changes compose vertically.
Squares certify compatibility.
Interchange makes local change compositional.

Require:

horizontal identities and composition
vertical identities and composition
square boundary typing
horizontal square pasting
vertical square pasting
interchange or explicit coherent comparison
one interpreter / double-functor lowering
effective normalization, resource, and invalidation policy

Select a pseudo double category when composition is coherent only up to a represented isomorphism or normal form. Select an equipment/framed bicategory only when strict maps admit effective companions, conjoints, or restrictions for generalized arrows. Select a virtual double category when generalized cells matter but horizontal composition is partial or intentionally unavailable.

Do not call a commutative-square fixture, a pair of categories, a PROP diagram, or double-pushout rewriting a double category by itself. Interchange never proves effect commutativity; preserve effect, authority, failure, provenance, schema meaning, and resource observations.

When selected, read references/double-category-architecture.md and references/mechanics/double-categories.md, then lower to the narrowest repository-native horizontal-arrow, vertical-arrow, square, pasting, and interpretation API needed by one witness seam.

Construction card decision table

For a consequential structural choice, state the ordinary candidate first, then consult references/universal-construction-registry.yaml and only card fragments relevant to the evidenced axis, typed hole, and requirements.

Construction cards are theorem nominations. They do not select a route or authorize mutation.

For each relevant card, record exactly one evidence-bound disposition:

• selected — prerequisites are evidenced, the card closes a real requirement gap, and lowering is effective;
• rejected — a named alternative dominates it in the declared comparison universe;
• contradicted — an attributed prerequisite is false or a falsifier is witnessed;
• unresolved — evidence is unknown, alternatives remain incomparable, or effectivity is not established.

The legacy card fields route and diagnostic_order are non-authoritative compatibility metadata. Signals are many-to-many pressure labels and never prove prerequisites.

Do not let signal count, evidence count, citation count, card order, categorical sophistication, or vocabulary manufacture a winner. Missing evidence remains unresolved; it is not obstruction. Support-only cards may guard the comparison universe but never become implementation artifacts.

The registry's universal.role: emitter means a selected artifact maps coherently into admissible consumers or interpretations. It never denotes an executable emitter.

Boundary Artifact Contract

A nominated direction is not yet selected architecture. Lower it into one repository-native Boundary Artifact Contract candidate. In Actuating composition, hand that candidate to Actuating without selecting the Construction. Complete every applicable field; use not applicable with an artifact-specific rationale rather than inventing ceremonial structure.

Context identifier / proof lease:
Boundary and owner:
Requirements discharged:
Representation / carrier:
Public constructors:
Public eliminators:
Legal compositions:
Two-dimensional arrows / squares / pasting, if selected:
Interpreter / projection / handler:
Required observations:
Compatibility / migration:
Bypass prevention:
Enforcement allocation:
Residual obligations:
Invalidation triggers:
Resource bound:
Claim strength:
Applicability rationales:

Construction surface

Every public constructor must make the invariant structurally unavoidable or perform the owner-controlled check before producing the artifact. Raw constructors and unchecked deserializers must not bypass the owner.

For a double-category artifact, square construction requires four matching boundaries. A strongly typed host should make mismatched edges unrepresentable; a weaker host returns one structured mismatch owned by the square constructor.

Elimination surface

Eliminators must be total over representable cases, expose only sanctioned observations, and preserve information needed by compatibility or later interpretation. Represent intentional partiality in the result type or named failure protocol.

Composition surface

Legal composition must be explicit and closed over valid artifacts. Illegal composition should be unrepresentable where possible; otherwise an owner-controlled combinator rejects it.

When two-dimensional composition is selected, expose separate horizontal and vertical composition plus horizontal and vertical square pasting. Internal shared boundaries disappear only through an explicit equality, normalization, or compatibility witness. Require interchange up to declared observations.

Interpretation surface

One explicit interpreter, projection, serializer, compiler, handler, renderer, or double-functor lowering owns semantics. It preserves required observations, effect order, compatibility, resources, and—when applicable—both arrow compositions, squares, pasting, and coherence.

Enforcement allocation

Every requirement has exactly one semantic owner and one primary disposition at the strongest honest locus the host permits: enforced, residual, or obstructed.

representation / type
opaque constructor
composition API
square constructor / pasting API
interpreter / handler
persistence or schema constraint
runtime boundary validation
monitoring / invalidation
residual obligation
obstruction

Additional guards are permitted only when derived from the same authority, preserving the same rule, declaring failure behavior, and carrying a conformance or drift witness. They provide defense in depth rather than competing ownership.

An enforcement matrix is complete only when every requirement maps to:

semantic owner / authority
primary disposition and locus
derived guard loci, if any
positive witness
failure behavior
conformance / drift witness
residual status
invalidation trigger

An orphan requirement is a correctness defect.

Correct-by-construction laws

A context-relative boundary artifact satisfies the applicable laws:

1. Construction soundness — every public construction satisfies allocated requirements.
2. Representational adequacy — every required admissible state is representable, residual, or obstructed.
3. Elimination totality — every representable case is handled and sanctioned observations survive.
4. Composition closure — lawful composition remains valid.
5. Composition admissibility — no illegal composition enters through a public path.
6. Interpretation preservation — lowering agrees with required semantics and observations.
7. Enforcement completeness — every requirement has one semantic owner and primary disposition; derived guards conform.
8. Bypass exclusion — unchecked construction, composition, and interpretation paths are absent or explicitly primitive.
9. Effectivity — construction, checking, normalization, interpretation, and invalidation fit the resource model.
10. Context validity — the proof lease remains valid under the recorded context and invalidation policy.
11. Two-dimensional coherence, when selected — square boundaries match, both pasting operations close, interchange holds up to declared equivalence, and interpretation preserves the square calculus.

Universal witness contract

A consequential categorical nomination needs more than a local law or commuting square:

Existence:
  the repository-native artifact or bounded approximation can be built.

Preservation:
  required observations, invariants, compatibility, and effects commute.

Mediation:
  every admissible competitor has the required comparison path.

Canonicality:
  the comparison is unique up to declared equivalence or normalization.

Effectivity:
  construction, comparison, validation, interpretation, and invalidation fit the budget.

Falsifier:
  a nearby weaker or illegal construction fails observably.

For a double-category claim, mediation means each admissible compatible change of a horizontal process is represented by a square and compatible local squares paste into a global square. Canonicality additionally requires the two pasting orders to agree by interchange up to declared equivalence.

Engineering realizations may approximate mediation and uniqueness through opaque constructors, canonical identifiers, normalized IR, one public interpreter, one sanctioned projection, generated code, removal of bypasses, or bounded search. State claim strength:

literal
effective realization
bounded approximation

A bounded approximation states what is included, excluded, possibly lost, and what evidence would refine it.

Residual obligations

A residual obligation is a requirement the artifact cannot honestly discharge at construction time. Record:

requirement
reason it remains residual
owner
check time
evidence needed
failure behavior
discharge condition

Residual obligations are first-class architecture. For double categories, unsupported arrow cases, unavailable square witnesses, partial companions/conjoints, or unbounded pseudo-coherence normalization remain residual rather than being silently totalized.

Invalidation triggers and proof leases

A correct-by-construction claim is a proof lease over the current context, not an eternal property of source code.

Record every change requiring revalidation, reconstruction, migration, or obstruction review:

requirements or policy
sanctioned observations or equivalence
schema / wire / storage version
external API semantics
authority or capability model
dependency or locality graph
effect ordering
host-language or module guarantees
resource budget
freshness horizon
horizontal or vertical arrow semantics
square boundary / pasting / coherence policy

When an invalidator fires, the artifact may remain executable but its architectural proof is stale. Prefer incremental invalidation of squares whose boundaries changed over global recomputation.

Evidence states and obstruction

Keep distinct:

evidenced true
evidenced absent
unknown / not inspected
underdetermined
witnessed obstruction

Unknown evidence is epistemic debt, not nonexistence. A real obstruction requires attributed counterevidence, a reproducible counterexample, stability under comparison maps, an effectivity account, a falsifier, and a reopening condition.

Return obstruction rather than inventing evidence, authority, policy, representability, effect laws, host capability, resource feasibility, square pasting, or interchange.

Doctrine index

The operational kernel above is authoritative. Load detailed references only when needed:

• references/universal-construction-registry.yaml and references/universal-constructions/
• references/structures-and-laws.md
• references/canonical-boundary-artifacts.md
• references/boundary-law-catalogue.md
• references/composition-geometry.md
• references/double-category-architecture.md
• references/mechanics/double-categories.md
• references/description-composition-doctrine.md
• references/effects-and-coalgebras.md
• references/comonadic-spatiality-doctrine.md
• references/exact-context-doctrine.md
• references/possibility-sheafification.md
• references/category-pivot.md
• references/mechanics/

Use the theorem name in expert reasoning; emit repository-native architecture by default.

Step -1 — World, boundary, and context inventory

For a non-trivial seam record:

World:
  objects:
  transformations:
  invariants:
  observations:
  primitives:
  composition:
  equality / coherence:

Boundary:
  kind:
  source:
  target:
  owner:
  preserved:
  forgotten:
  generated:
  observed:

Context:
  requirements:
  authority:
  compatibility:
  effects:
  resources:
  host capabilities:
  validity horizon:

Typed hole:
  axis:
  kind:

Two-dimensional structure, when relevant:
  horizontal arrows and composition:
  vertical arrows and composition:
  square meaning:
  pasting and interchange:

Do not escalate when this inventory cannot be grounded in repository evidence.

Step 0 — Allocate an independently durable plan

When Decision durability applies, first load $ledger and complete $ledger ensure once. Then allocate a fresh plan:

ledger --source universalist create \
  --repo PROJECT_ROOT \
  --template /path/to/universalist/templates/universalist-plan.md

Resolve it with:

ledger --source universalist path --repo PROJECT_ROOT --id PLAN_ID
ledger --source universalist latest --repo PROJECT_ROOT

Before mutation, write the current-context contract, composition owner and decision carrier, ordinary candidate, comparison universe, axis and typed hole, relevant card dispositions, Boundary Artifact Contract with applicability rationales, enforcement matrix, residual obligations, invalidation triggers, proof lease, law, falsifier, and any horizontal/vertical/square/pasting obligations into the plan.

After standalone root adjudication emit exactly one receipt:

ledger --source universalist emit \
  --plan PLAN_PATH \
  --contract /path/to/universalist/references/decision-contract.yaml \
  --clause-ref UNI-DISPOSITION-001 \
  --clause-ref UNI-MINIMAL-001 \
  --clause-ref UNI-CONTEXT-001 \
  --clause-ref UNI-ARTIFACT-001 \
  --clause-ref UNI-ENFORCEMENT-001 \
  --clause-ref UNI-MECHANICS-001 \
  --clause-ref UNI-DOUBLE-001 \
  --clause-ref UNI-ROOT-001 \
  --question "Which context-relative boundary artifact owns this seam?" \
  --selected-route UNI-CANONICAL \
  --rejected-route UNI-ORDINARY \
  --expected-outcome "One owner enforces the current requirements." \
  --disposition changed \
  --construction "typed process/change compatibility-square calculus" \
  --law "boundary-matched local squares paste and satisfy interchange under required observations" \
  --falsifier "a mismatched square or observation-changing interchange is accepted" \
  --advanced-mechanics double-category \
  --evidence-ref "code:path" \
  --write-plan

Pass only applicable clauses explicitly. Add UNI-DOUBLE-001 only when two-dimensional composition is selected. Add UNI-ROOT-001 only for independently durable decisions. UNI-OBSTRUCT replaces UNI-ARTIFACT-001 with UNI-OBSTRUCTION-001. Reclassification adds UNI-RECLASSIFY-001 and trigger UNI-RECLASSIFY.

Ledger owns plan identity, addressing, receipt construction, validation, and atomic append. Universalist owns architecture policy. The contract is the machine-readable authority for triggers, routes, clauses, and required evidence; this file supplies operational semantics. Change the skill, contract, and plan template together. Seq validates structure and fingerprinting, not prose-to-contract equivalence.

Decision observability

A route is consequential only when at least two plausible routes materially differ in persistent behavior, authority, compatibility, migration, enforcement, invalidation, or proof obligations. Apply this initially and whenever reclassification sees material evidence.

Consequential decisions require:

current-context contract
ordinary candidate
comparison universe
one axis and typed hole
composition context, decision owner, and carrier
relevant cards and dispositions
Boundary Artifact Contract with applicability rationales
material delta
selected and rejected routes
law and falsifier
resource impact
enforcement matrix
residual obligations
invalidation triggers / proof lease

An independently durable decision additionally requires one ledger-addressed plan, one root SDR-v1, and applicable clause refs. An Actuating-composed decision uses the current Construction instead.

Routes are assigned only after lowering:

• UNI-PRESERVE — an already exact boundary remains unchanged.
• UNI-ORDINARY — the smallest repository-native artifact closes the seam without material advanced-construction delta.
• UNI-CANONICAL — a theorem-card direction materially strengthens the ordinary candidate and has a complete effective witness.
• UNI-OBSTRUCT — no honest representable or effective artifact is justified, or a primitive bypass is explicitly contained.

A card's legacy route hint never determines the choice.

Tracks

• Track A0 — Domain Algebra Discovery: carriers, operations, observations, laws, non-laws, and effect boundaries.
• Track A — Diagnosis: analyze one seam without mutation.
• Track B — One-seam refactor: implement one narrow owner-controlled artifact.
• Track C — Staged migration: strengthen internals behind stable wire, API, or storage shapes.
• Track D — Canonical boundary artifact: use theorem cards to strengthen one typed hole.
• Track E — Composition certification: make legal one-dimensional composition or a selected two-dimensional square/pasting calculus explicit.
• Track F — Exact Context: prepare certified context before semantic consumption.
• Track G — Possibility Sheafification: reconcile local meanings into an exact global abstraction.
• Track H — Category Pivot: move one hard operation to a world where it is explicit, then transport it back.
• Track I — Effective universal substrate: design a whole capability with concrete primitives, recursion/partiality, effects, state, observations, and resources.

Every track lowers to the applicable Boundary Artifact Contract profile; inapplicable surfaces require a concrete rationale.

Team mode

Do not spawn Universalist subagents unless the user explicitly requests subagents, parallel agents, team mode, or the categorical-substrate team.

When authorized:

1. use the smallest sufficient read-only roster;
2. give each agent one axis and typed hole, including square when two-dimensional composition is under review;
3. require evidence, card dispositions, residuals, and invalidators;
4. let the root synthesize one Boundary Artifact Contract candidate;
5. have the proof auditor attack it;
6. use one writer for one witness seam;
7. use the verifier independently;
8. emit a root receipt only when independently durable.

Child agents do not choose routes, authorize mutation, or recursively spawn agents.

Output contract

Normal output uses repository and domain language:

Separate executable process composition from migration composition.
Introduce one typed compatibility-square witness.
Permit only boundary-matched horizontal and vertical pasting.
Verify that local migration witnesses paste into the same global result in either order.
Invalidate affected squares when an interface or process boundary changes.

When expert explanation is requested, add the construction name, hypotheses, competitors, mediator, canonicality claim, effective lowering, claim strength, and obstruction boundary.

Stop after the first verified seam unless the user explicitly widens scope.