propagate

Propagation

This skill generates tests from Allium specifications. Propagation is how plants reproduce from cuttings of the parent: the spec is the parent, the tests are the offspring.

Deterministic tools guarantee completeness (every spec construct maps to a test obligation). You handle the implementation bridge: correlating spec constructs with code, generating tests in the project's conventions.

Interaction modes

This skill runs in two modes. Every instruction below that asks or suggests something to the user follows the mode:

• Interactive — running inline in a conversation. Ask the user directly and wait for the answer.
• Non-interactive — running as the propagate subagent (for example inside the Allium loop), where no user is reachable. Report anything that needs a human decision — a spec too coarse to propagate, an ambiguous implementation bridge, uncovered obligations — in your final output and continue with the work that does not depend on it.

Prerequisites

Before propagating tests, you need:

1. An Allium spec — the .allium file describing the system's behaviour
2. A target codebase — the implementation to test
3. Test obligations — from allium plan <spec> (JSON listing every required test)
4. Domain model — from allium model <spec> (JSON describing entity shapes, constraints, state machines)

If the CLI tools are not available, derive test obligations manually from the spec using the test-generation taxonomy in references/test-generation.md.

Modes

Surface mode

Generates boundary tests from surface declarations. Use when the user wants to test an API, UI contract or integration boundary.

For each surface in the spec:

1. Exposure tests — verify each item in exposes is accessible to the specified actor, including for iteration over collections
2. Provides tests — verify operations appear when their when conditions are true and are hidden otherwise, including when the corresponding rule's requires clauses are not met
3. Actor restriction tests — verify the surface is not accessible to other actor types
4. Actor identification tests — verify only entities matching the actor's identified_by predicate can interact; for actors with within, verify interaction is scoped to the declared context
5. Context scoping tests — verify the surface instance is absent when no entity matches the context predicate
6. Contract obligation tests — verify demands are satisfied by the counterpart, fulfils are supplied by this surface, including all typed signatures
7. Guarantee tests — verify @guarantee annotations hold across the boundary
8. Timeout tests — verify referenced temporal rules fire within the surface's context
9. Related navigation tests — verify navigation to related surfaces resolves to the correct context entity

Spec mode

Walks the full test obligations document. Use when the user wants comprehensive test coverage for the entire specification.

Categories from the test-generation taxonomy:

• Entity and value type tests — fields, types, optional (?) null handling, when-clause state-dependent presence, relationships, join lookups, equality
• Enum tests — comparability across named enums, membership tests, inline enum isolation
• Sum type tests — variant fields, type guards, exhaustiveness, creation via variant name, base .created trigger narrowing
• Derived value and projection tests — computation, filtering, -> field extraction, parameterised derived values, now volatility, collection operations
• Default instance tests — unconditional existence, field values, cross-references between defaults
• Config tests — defaults, overrides, mandatory parameters, expression-form defaults, qualified references, config chains
• Invariant tests — post-rule verification, edge cases, implication logic, entity-level invariants
• Rule tests — success/failure/edge cases, conditionals (ensuring if guards read resulting state), entity creation, removal, bulk updates, rule-level for iteration, let bindings, chained triggers
• State transition tests — valid/invalid transitions, terminal states, transitions_to vs becomes semantics
• Temporal tests — deadline boundaries, re-firing prevention, optional field null behaviour
• Surface tests — exposure, availability, actor identification with within scoping, context scoping, related navigation
• Contract tests — signature satisfaction, @invariant honouring, demands/fulfils direction
• Cross-module tests — qualified entity references, external trigger responses, type placeholder substitution
• Cross-rule interaction tests — duplicate creation guards, provides availability
• Transition graph tests — every declared edge is reachable via its witnessing rule, undeclared transitions are rejected, terminal states have no outbound rules, non-terminal states have at least one exit, exact correspondence between enum values and graph edges
• State-dependent field tests — presence when in qualifying state, absence when outside, presence obligations on entering the when set, absence obligations on leaving, no obligation when moving within or outside, convergent transitions all set the field, guard required to access when-qualified fields, derived value when inference via input intersection
• Scenario tests — happy path, edge cases, order independence
• Data flow chain tests — exercise full chains from surface capture through rules to downstream rule preconditions. For each chain (surface provides trigger → rule ensures field → downstream rule requires field), generate an integration test that submits data through the surface and verifies it reaches the downstream precondition.
• Reachability tests — walk from each initial state (via .created()) to each terminal state, following a valid path through the transition graph. Each test exercises a complete lifecycle.
• Deadlock scenario tests — for states where allium analyse identifies potential deadlocks, generate tests that put the entity in the stuck state and verify whether it can progress.
• Cross-entity process tests — for processes spanning multiple entities, generate integration tests that exercise the full process from start to terminal state across all participating entities.

If allium analyse is available, use its findings to prioritise test generation. A missing_producer or dead_transition finding indicates a gap worth exercising with a test. A deadlock finding should generate a test documenting that the entity cannot escape the stuck state. Consult actioning findings for the finding type taxonomy.

Test output kinds

1. Assertion-based tests

For deterministic obligations: field presence, enum membership, transition validity, surface exposure, state-dependent field presence and absence. These are standard unit/integration tests.

2. Property-based tests

For invariants and rule properties. Each expression-bearing invariant becomes a PBT property:

• Generate a valid entity state using the generator spec
• Apply a sequence of rules (following the transition graph when declared, or deriving valid sequences from rules alone)
• Check the invariant holds at every step

Use the project's PBT framework:

Fall back to assertion-based tests if no PBT framework is present.

3. State machine tests

For entities with status enums. When a transition graph is declared, walk every path through the graph. When no graph is declared, derive valid transitions from rules.

• Verify transitions succeed via witnessing rules
• Verify rejected transitions fail
• Verify state-dependent fields are present or absent at each state per their when clauses
• Verify invariants hold at each state

State machine tests require an action map: a function per transition edge that takes the entity in the source state and produces it in the target state by calling the actual implementation code. Without this map, the test framework can describe valid paths through the graph but cannot execute them.

To build the action map:

1. For each edge in the transition graph, find the witnessing rule in the spec
2. Find the code implementing that rule (the implementation bridge)
3. Write a test action that sets up the preconditions (requires clauses), invokes the code, and returns the entity in the target state
4. Register the action under the (from_state, to_state) key

Once the map is built, the PBT framework can walk random valid paths: start at any non-terminal state, pick a random outbound edge, apply its action, check all entity-level invariants, repeat. The path length and starting state are generated randomly. This is the fullest expression of the spec's transition graph as a test.

The implementation bridge

You correlate spec constructs with implementation code, the same way the weed skill correlates for divergence checking.

For surface tests

Map surfaces to their implementation:

• API surfaces map to endpoints (REST routes, GraphQL resolvers, gRPC services)
• UI surfaces map to components or pages
• Integration surfaces map to message handlers or SDK methods

Discover the mapping by reading the codebase. Look for naming patterns, route definitions and handler registrations.

For internal tests

For each rule in the spec:

1. Find the code implementing the rule (service method, event handler, state machine transition)
2. Determine how to instantiate the entities involved (factories, builders, fixtures)
3. Determine how to invoke the rule (API call, method call, event dispatch)
4. Determine how to assert postconditions (database queries, return values, event assertions)

For temporal tests

Temporal triggers (deadline-based rules) need a controllable time source in the test. If the implementation uses wall-clock time (Instant.now(), System.currentTimeMillis()), the test cannot reliably position itself before, at or after a deadline.

Before attempting temporal tests, check whether the component accepts an injected clock or time parameter. Common patterns: a Clock parameter on the constructor, an epoch-millisecond argument on the method, a TimeProvider interface. If the seam exists, inject a controllable time source. If it does not, flag this as a test infrastructure gap: the temporal tests cannot be generated until the component supports time injection. Do not attempt to test temporal behaviour by sleeping or racing against wall-clock time.

For cross-module trigger chains

When a rule emits a trigger that another spec's rule receives (e.g. the Arbiter emits ClerkReceivesEvent, the Clerk handles it), testing the chain requires multiple components wired together.

Before generating cross-module tests:

1. Trace the trigger emission graph from the plan output: which rules emit triggers, and which rules in other specs receive them
2. Check whether the codebase has an existing integration test fixture that wires the participating components (a pipeline test, an end-to-end test helper, a test harness class)
3. If a fixture exists, reuse it. Cross-module tests should compose existing wiring, not rebuild it
4. If no fixture exists but the codebase structure is clear enough to understand the wiring (service constructors, dependency injection, event bus configuration), generate the fixture and the test
5. If the wiring is too complex or opaque to generate confidently, generate a test skeleton with TODOs marking where component wiring is needed

Cross-module tests are integration tests by nature. They verify that the spec's trigger chains are faithfully implemented across component boundaries. Prioritise them after single-component tests are passing.

Reusing existing tests

When exploring the codebase, note which spec obligations are already covered by existing tests. An existing integration test that exercises the happy path from event submission through to acknowledged output already covers multiple rule_success obligations and the end-to-end scenario.

When an existing test covers a spec obligation, reference it rather than generating a duplicate. The propagate skill's value at the integration level is verifying that coverage is complete against the spec's obligation list, identifying gaps, and generating tests to fill them — the reconciliation step in the process below makes this check explicit. Replacing working hand-written tests with generated equivalents adds no value.

For deferred specs

Deferred specifications are fully specified in separate files. When the target codebase doesn't include the deferred spec's module, generate a test stub with a placeholder:

// TODO: deferred spec — InterviewerMatching.suggest
// This behaviour is specified as deferred. Provide a mock or skip.

Process

1. Read the spec — understand entities, rules, surfaces, invariants, transition graphs, state-dependent fields, contracts, config, defaults. Read assessing specs to gauge the spec's maturity. A coarse spec (entities and transition graphs but no rules) will produce limited test obligations — mostly structural tests. If the spec is too coarse for meaningful test generation, suggest using the elicit or distill skill to develop it further before propagating tests. A spec with rules and surfaces enables the full test taxonomy including data flow chain tests and reachability tests.
2. Read test obligations — from allium plan output or manual derivation
3. Read domain model — from allium model output or manual derivation
4. Explore the codebase — find existing tests, test framework, entity implementations, rule implementations
5. Map constructs to code — correlate spec entities/rules/surfaces with implementation classes/functions/endpoints
6. Generate tests — produce test files following the project's conventions
7. Verify tests compile/run — ensure generated tests are syntactically valid
8. Reconcile obligations — confirm every obligation maps to a covering test, and auto-cover any gaps (see Obligation reconciliation)

Discovery checklist

Before generating tests, establish:

• Test framework and runner (Jest, pytest, cargo test, etc.)
• PBT framework if present (fast-check, Hypothesis, proptest, etc.)
• Test file location conventions (co-located, __tests__/, tests/, etc.)
• Entity/model location and patterns (classes, interfaces, structs)
• Factory/fixture patterns for test data
• How state transitions are implemented (methods, events, state machines)
• How surfaces are implemented (routes, controllers, resolvers)
• Existing test helpers or utilities
• Whether components accept injected time sources for temporal tests
• Whether an integration test fixture exists for cross-module trigger chains
• Which spec obligations are already covered by existing tests

Generator awareness

When generator specs are available, use them to produce valid test data:

• Respect field types and constraints
• For entities with transition graphs, generate entities at specific lifecycle states with correct field presence per when clauses (e.g. a shipped Order has tracking_number and shipped_at populated; a pending Order does not)
• For invariants, generate states that exercise boundary conditions
• For config parameters, use declared defaults unless testing overrides

Obligation reconciliation

After generating tests, walk the full obligation list — from allium plan output or the manual derivation — and map each obligation to the test that covers it, whether generated this run or pre-existing. Reconciliation is silent: obligations are internal working data, so do not narrate the mapping, print the obligation list or present a coverage report while everything is on track.

For each obligation with no covering test, attempt to cover it:

1. Generate the missing test, or extend an existing test that partially covers it
2. Verify the new test compiles and runs
3. Re-check the obligation against the result

This is a mini-loop, and it needs the same guards as the outer Allium loop (see driving the loop):

• Attempt cap — at most 2 attempts per obligation. If the second attempt does not produce a compiling test that covers it, park the obligation.
• No-progress cap — if a full pass over the remaining gaps covers nothing new, stop; further passes will thrash.

Obligations still uncovered when a guard trips are the only part of reconciliation the user sees. Report each with a classification and a one-line reason:

• Infrastructure gap — the test needs a seam the code does not provide: no injectable clock for a temporal obligation, no integration fixture for a cross-module chain
• Unmappable construct — in a code-first flow, no implementation code correlates with the spec construct; the implementation bridge could not be built

Missing implementation is not a residue category. In a spec-first flow no code exists yet by design: write the test against the intended interface and let it fail — a failing test covers its obligation, and the loop's implement phase turns it green. An obligation is uncovered only when no test for it could be written at all.

Close with a single summary line: N obligations, M covered, K uncovered. When everything is covered that one line is the entire user-facing output of reconciliation. Silence about an individual obligation means it is covered; anything itemised needs a human decision. When propagate runs inside the Allium loop, this line feeds the loop's consolidated summary, and the loop must not treat the spec as converged while obligations remain uncovered without a reported reason.

Recording the tamper baseline (in the loop)

When running inside the Allium loop, record the reconciliation baseline so the loop's independent witness can later confirm nothing was falsified. In the ledger (.allium-loop/<goal-slug>.json, see driving the loop):

• write a content hash (e.g. sha256) for each generated test file under generated_test_hashes, keyed by path;
• record the reconciliation summary line under reconciliation.

The hash is the ground truth the witness skill re-derives: a generated test whose hash changes with no intervening propagate run is a hand-edited test — the anti-cheat violation the loop must never reach convergence with. Recording the baseline is what makes that check possible; skip it and the witness can confirm the tests pass but not that they were not weakened. This is cheap bookkeeping, not a report — do not narrate it.

Typed result (loop hand-off)

When running as the propagate subagent inside the Allium loop, return your result as a single JSON object conforming to propagate-result.schema.json, and nothing else. The loop routes on the structured fields: obligations and uncovered_obligations decide whether coverage is complete (the loop must not converge while uncovered_obligations is non-empty), and generated_tests carries the path-and-hash baseline the witness re-derives — the same hashes recorded above, now first-class in the hand-off. Keep the summary field to the N obligations, M covered, K uncovered line. Emit every field, using [] for empty lists — do not omit them. Running interactively, the summary line remains the whole user-facing output as before — the typed record is for the machine hand-off, not the conversation.

{
  "phase": "propagate",
  "obligations": { "total"

Interaction with other tools

• distill produces specs from code. Those specs feed propagate.
• weed checks alignment. After propagating tests, weed verifies spec-code match.
• tend evolves specs. After spec changes, run propagate again to update tests.
• elicit builds specs through conversation. Once a spec is ready, propagate generates tests.

Limitations

• Generated tests are a starting point. They may need adjustment for project-specific patterns.
• The implementation bridge is LLM-mediated. Complex or unusual codebases may need manual guidance on the mapping.
• Cross-module tests require understanding component wiring across service boundaries. When the codebase structure is clear, full tests can be generated. When wiring is opaque, tests are generated as skeletons with TODOs for manual setup.
• Runtime trace validation and model checking are separate workstreams.