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.