Morphogenetic Architecture

Shape software topology through local rules, declared boundaries, and measured pressure. Preserve the Domain / abstraction tier / layer placement model as the declared skeleton; use observed relationships to test and evolve that skeleton instead of treating the initial grid as permanent truth.

The workflow itself follows morphogenesis: the declared topology acts as a genetic scaffold, observed fields expose developmental pressure, topology decisions differentiate or remodel the structure, and verification maintains homeostasis. Treat this as a disciplined transfer of mechanisms, not a claim that software is literally alive.

Core Directives

1. Declare before observing. Record intended placement and allowed dependency direction before using telemetry or history to challenge it.
2. Keep projections distinct. Keep static imports, runtime interaction, change affinity, shared data, and failure propagation as separate graphs. Never hide an invalid static edge inside an acceptable runtime cycle.
3. Prefer local rules. Make each component depend on a small, named neighbor set through explicit inbound and outbound interfaces.
4. Evolve from evidence. Move, split, or merge only when domain meaning and observed pressure support the same change. Treat algorithms as candidate-cut generators, never as domain authority. Accept computed graph evidence only from retained executable output, never from a narrated calculation. When pressure cannot yet be measured, the probationary path in §5 may apply; measured contradiction always blocks.
5. Transfer mechanisms, not silhouettes. When a natural mechanism supplies a second candidate, record the generator-free baseline first, use one indexed mechanism to generate a distinct alternative or expose a missed risk, and predeclare what would reject it. Then let software evidence accept or reject both candidates. Never choose a topology because it resembles a spiral, tree, honeycomb, or sacred figure.
6. Preserve one owner per rule. Hand complexity measurement to structural-simplification, internal design to architecture-guidelines, and enforceable edges to architecture-as-code.
7. Escalate proof monotonically. Start with the smallest sufficient analysis mode, but never let a request for speed waive evidence, measurement, or hard-invariant checks.
8. Scale proof to reversibility. Grade how expensive the change would be to undo, then require evidence proportional to that cost. A cheap-to-reverse change still obeys every hard invariant; a hard-to-reverse change is never accepted on one field.
9. Close the loop. Every accepted restructuring is a hypothesis: record the field it should improve, the window, and the recheck trigger, then re-enter Audit when the window closes. Route a systematic prediction miss to continuous-improvement.

Select the Analysis Mode

Select and report the analysis mode before collecting evidence. User wording chooses the starting mode; the rules below choose the minimum proof standard.

Mode	Use for	Evidence surface	Available final decisions
Rapid	One bounded placement, a small static-edge check, or declaration of one already-identified runtime loop	Declared placement, static dependencies, and the named loop's bound / owner / observability	PLACE, KEEP, DECLARE-RUNTIME-CYCLE, DEFER
Full	Restructuring, multi-field evidence, broad topology, ambiguity, or a deep audit	Declared topology plus every available static, runtime, change, data, and failure field	All decisions in §6

Apply this deterministic selector:

1. Start in Full when the user explicitly requests a full topology analysis, deep architecture audit, evidence-driven redesign, or a subsystem/service-graph architecture audit. A bare Alchemy FULL dispatch traverses gates but does not override this skill's selector.
2. Otherwise start in Rapid and read references/rapid-topology-scan.md.
3. Escalate from Rapid to Full before selecting a decision when any of these conditions appears:
   • MOVE, SPLIT, MERGE, or INTRODUCE-BOUNDARY becomes a candidate;
   • a decision depends on runtime pressure, co-change, shared data, failure propagation, weighting, or graph partitioning rather than merely declaring one bounded runtime loop;
   • the scope crosses several domains/components or a material ownership, security, compliance, or failure boundary;
   • placement is ambiguous, observed signals conflict, or the Rapid result cannot be justified from declared topology and hard invariants alone.
4. Once Full begins, do not downgrade because evidence is unavailable. Record missing fields as Not measured and emit DEFER when the proof requirement cannot be met.

An explicit rapid or quick request may select the starting mode, but it cannot authorize a restructuring decision. Rapid must either finish with one of its four decisions or record Rapid → Full and continue at Full. Do not rerun checks already completed unless Full requires a broader evidence scope.

Reporting Vocabulary

Use coder-facing terms in every report:

Concern	Coder-facing field
Business placement	Domain — a bounded context; allow nested paths such as commerce/payments
Responsibility scale	Abstraction tier — orchestrator → capability → primitive
Environment depth	Layer — consumer → application/domain → infrastructure
Entry surface	Inbound interface — the public contract callers use
Dependency surface	Outbound interface — declared calls, I/O, or infrastructure access
Vertical relationship	Caller / callee
Same-tier relationship	Peer / sibling
Intended structure	Declared topology
Measured relationships	Observed fields
Repeated evidence against a boundary	Boundary pressure
Low-pressure candidate separation	Candidate boundary
Thing being placed	Component
Its declared address	Position

Keep layer and abstraction tier separate. Keep component (the thing) and position (where it belongs) separate.

Living-System Translation

In Full mode, keep the natural analogy visible throughout the workflow. It is a way of thinking about the workflow, not a report field. An analogy request that could affect the decision escalates to Full.

Morphogenetic role	Software meaning
Genetic scaffold	Declared topology, invariants, and allowed interfaces
Morphogen fields	Static, runtime, change, data, and failure pressure
Differentiation	PLACE, MOVE, or SPLIT into a clearer responsibility
Remodeling / pruning	MERGE, remove an edge, or retire an obsolete component
Homeostasis	Bounded feedback, observability, verification, and enforcement

A natural mechanism reaches the report only as a §4 second candidate with generator natural lens, and only after it satisfies the atlas's Candidate-Contribution Test. Read references/natural-pattern-atlas.md before using one. A mechanism that adds nothing to the generator-free baseline, or that no unused independent field or held-out window can falsify, contributes nothing and is not reported.

1. Declare the Skeleton

Assign every component a position:

Domain / abstraction tier / layer

Apply these placement rules:

• Place one cohesive capability at one primary position.
• Model subdomains as nested domain paths; do not force a naturally nested capability into a flat domain list.
• Connect an outbound interface only to an allowed inbound interface.
• Expose internals only through the component's inbound interface.

Preserve dependency inversion: source-code imports may point toward an abstraction even when runtime control flows toward infrastructure.

Position Legality

Check the edges of the component being placed: a design-time check on a proposed or changed position, a handful of edges at a time, never a whole-codebase audit from three axes. Each proposed edge satisfies one clause per axis — layer (ordinal: same layer, one step toward infrastructure, or toward the consumer only through dependency inversion), abstraction tier (ordinal: same tier, or a higher tier calling a lower one), and domain (categorical: the same path, a nested path, or the target's declared inbound interface). Two whole-graph clauses complete it: the static projection is acyclic, reported in Static cycle, and code reaches an external SDK only inside its owning adapter. The clauses need no observed field, run before §3, and decide the seven findings §5 names; turn every result into architecture-as-code rules that name each edge and its reason. Read references/position-legality.md for the clause table, the definitions of inbound interface, re-export module, and external SDK, the composition-root exemption, placement ambiguity, and the Not applicable rule. Legality is necessary, never sufficient — a legal edge can still be wrong for reasons only §3's fields expose.

2. Separate Static and Runtime Topology

Define the projection before judging a cycle:

Projection	Required shape	Typical evidence
Static dependency	Directed, acyclic per component, shallow	Imports, package edges, build references
Ownership / authority	Directed, acyclic per concern	Declared owners, handoffs, decision records
Runtime request flow	Directed; cycles allowed only when named and bounded	Traces, RPC calls, message routes
State transition / feedback	Cycles allowed with explicit semantics	State machines, retries, event loops
Change affinity	Undirected weighted evidence	Co-change history
Shared-data coupling	Directed or undirected, declared per dataset	Schema ownership, reads/writes
Failure propagation	Directed weighted evidence	Incidents, retry storms, cascading errors

Reject every forbidden static cycle. For an intentional runtime cycle, name its termination condition, retry/iteration bound, owner, and observability. Do not use a queue, registry, callback, or event bus to conceal static ownership.

Authority is acyclic per concern, not per component. Two components may each defer to the other on a different concern — one owning meaning while the other owns measurement, say — and that is a clean partition, not a cycle. Name the concern on every authority edge; a cycle exists only when two components claim authority over the same one. Import cycles have no such escape: a build cannot order them however the concerns are split.

3. Observe Pressure

Run this section in Full mode. Rapid records proposed or current static edges and may declare one already-identified runtime loop; needing any other observed field triggers escalation.

Use only evidence available for the system. Mark missing fields Not measured; never replace absent telemetry with intuition.

A greenfield or young system legitimately reports Not measured on every historical and runtime field; that is absence of history, not a defect. §1's position legality still runs at full strength there — it needs no field — and it is this skill's whole contribution until the first field becomes measurable. Decide placement from domain meaning, declared topology, and position legality, and for a placement that establishes a new cross-domain or cross-layer edge, predeclare in Prediction the future validating field, its expected direction, the evidence window, and the recheck trigger. A restructuring in an evidence-poor system follows the probationary path in §5.

Collect:

• Static dependency pressure — imports or calls that cross a declared boundary.
• Runtime-flow pressure — traffic volume, latency, or coordination across positions.
• Change pressure — files or components that repeatedly change together.
• Data pressure — shared schemas, state, transactions, or write ownership.
• Failure pressure — faults that propagate across boundaries or depend on a single critical path.

Read references/evidence-fields.md when an audit uses history, telemetry, weighted fields, or graph partitioning. Keep the core placement workflow in this file.

Before calculating a weighted candidate, declare that field's baseline, metric, threshold, evidence window, minimum candidate size, and sensitivity rule. Do not tune the policy after seeing a preferred cut. A hard invariant such as a forbidden static cycle does not need a numeric threshold, but its graph result must still be reproducible.

Read references/graph-analysis.md and run the bundled analyzer when computing SCCs, Fiedler/spectral cuts, normalized cuts, conductance, or sensitivity. If no executable output is available, mark graph analysis Not measured and do not report an algorithmic candidate.

Record which field values and windows produced the question, finding, and generator-free baseline. Discovery evidence may generate that baseline, but the same observations cannot later count as prospective falsification of a second candidate.

4. Generate a Second Candidate

In Full mode, first record the candidate suggested by declared topology, domain meaning, hard-invariant checks, and the discovery evidence already inspected; none is a valid baseline. Rapid skips this section.

Before accepting a Medium- or Low-reversibility restructuring, generate one independent second candidate or record Second candidate: none with the reason no generator produced a distinct viable alternative. Any generator qualifies, each under its own discipline:

• an algorithmic cut from §3 — declared policy, sensitivity check, and retained executable output;
• a natural lens from references/natural-pattern-atlas.md — enter through its Operational Lens Index, select at most one lens, and satisfy its Candidate-Contribution Test before the candidate counts;
• a manual alternative decomposition along a different axis (domain, abstraction tier, or layer) — its rejection condition named before its validation surface is inspected.

A High-reversibility change may mark the field Not required — high reversibility. PLACE, KEEP, and DECLARE-RUNTIME-CYCLE omit the field with the rest of the §8 restructuring set, and Rapid never emits it; a DEFER that withholds a restructuring marks it Not required with a short reason. A second candidate widens the option set; it never lowers the evidence bar, and baseline and second candidate face the same software-evidence policy. Second candidate: none must name which generators were attempted and why each produced nothing distinct; a second candidate that is produced and rejected records its rejection under the same evidence policy as the baseline.

Whatever the generator, name the rejection condition and its validation surface before inspecting that surface, then test baseline and second candidate under the same software-evidence policy. Use a retained contribution to extend the candidate set or expose risk, not to replace evidence. A hard invariant such as a forbidden import cycle needs no second candidate. The generator's name, mechanism, or analogy may never appear in Boundary evidence.

5. Diagnose Mismatches

§1's position legality already decides seven findings without any observed field: layer-skip violation, layer inversion, tier inversion, cross-domain coupling, forbidden import cycle, external SDK bypass, and placement ambiguity when the check cannot run. Those are enforced by architecture-as-code as named edges; report the violation and fix it, and do not re-argue them from evidence here.

The findings below need observed evidence. Use these names and tests:

Finding	Test
god component	One component owns unrelated edge clusters or multiple independent change reasons
hidden runtime coupling	A bus, registry, callback, global, or shared state creates an undeclared edge
boundary-pressure mismatch	Multiple observed fields repeatedly cross a declared boundary
false boundary	Components share purpose, lifecycle, and strong affinity but are separated without an independent reason
resilience bottleneck	One component or edge carries disproportionate failure impact without an explicit recovery path
topology drift	Declared rules and current static/runtime evidence no longer agree

Treat a single noisy signal as a review prompt. Require a domain reason plus an independent observed field whose predeclared policy is met before changing a boundary, unless §1's position legality already decides the case or the probationary path below substitutes its expiry, instrumentation, and reversal record for an absent field. That is the floor; the reversibility grade below decides how much field agreement and evidence window it takes to clear it. Return DEFER when a threshold or sensitivity rule is missing, retrofitted, or unstable.

Scale Proof to Reversibility

Grade the cost of undoing the proposed change before setting its evidence bar. Grade only when a boundary actually moves: before accepting MOVE, SPLIT, MERGE, or INTRODUCE-BOUNDARY, and when DEFER withholds one of them. PLACE, KEEP, and DECLARE-RUNTIME-CYCLE omit the restructuring set entirely — they fill or bound an existing position rather than change one.

The grade uses declared facts — consumers, published contracts, data, and deployment coupling — so it needs no weighted evidence and no extra analysis mode.

Reversibility	Signals	Evidence bar for a boundary change
High	One owner, internal callers only, no published contract, no data migration, one deployable	Domain reason plus one independent field; a shorter evidence window is acceptable when the reversal path is named
Medium	Several internal consumers, a shared internal contract, reversible data change, or a coordinated deploy	Domain reason plus one independent field meeting its declared policy, plus the sensitivity check for any generated candidate
Low	External or cross-team consumers, a published or versioned contract, irreversible data migration, or a separate deployment/ownership boundary	Domain reason plus two independent applicable fields that each meet their declared policy and support the same boundary; at least one field must have authority over the dominant reversal-cost driver. Also require a passing sensitivity check for any generated candidate and a staged path whose reversal step is explicit. If only one field is available, emit DEFER for the Low-reversibility end state; a separately specified precursor may proceed only after it is graded independently and meets its own evidence bar.

Grade from the least-reversible known signal. When the facts needed to exclude a Low signal cannot be stated, report Reversibility: Unknown — Low bar applies, name the missing consumer, contract, data, deployment, or ownership facts in Next action, and do not accept the Low-reversibility end state until they are resolved. Grade any separately specified precursor independently.

Reversibility never lowers a hard invariant, never authorizes a Rapid restructuring decision, and never substitutes for the §7 structural measurement.

Probationary Acceptance

When every hard invariant passes, the §7 structural measurement is met, and the only missing proof is a required observed field that cannot be measured within the decision window — no history yet, no instrumentation in place, or an infeasible measurement cost — accept the restructuring probationarily instead of holding an indefinite DEFER:

• Reversibility must be High, or Medium with a named reversal path. Low or Unknown reversibility never accepts probationarily.
• Probation covers absent evidence only. A measured field that contradicts the change, a failed declared policy, or a defective policy on a measured field still blocks; probation never overrides disagreement.
• Absent means unobtainable, not unfetched. A field derivable from the repository or VCS history already present — co-change and schema/data ownership above all — is never eligible for probation; measure it first.
• Record in Boundary evidence: probationary — <domain reason> + <why the field cannot be measured> + expiry or revisit trigger + instrumentation task + reversal path.
• Record in Prediction the field the instrumentation will measure, the expected direction, and the evidence window.
• At expiry, re-enter this skill in Audit mode on the bounded scope. A confirmed prediction upgrades the acceptance to measured; a miss triggers the reversal path or an explicit re-decision — never silent retention.
• The path exists only in Full; Rapid still finishes with its four decisions.

6. Choose the Smallest Evolution

Select one decision:

Decision	Apply when
PLACE	A new component has one clear position, interface, and allowed neighbor set
KEEP	Declared placement and observed evidence agree
MOVE	One component has a clear primary position elsewhere
SPLIT	Independent capability/change/failure clusters occupy one component
MERGE	A boundary separates one purpose and lifecycle without reducing coupling or risk
INTRODUCE-BOUNDARY	Cross-position access needs one explicit contract or adapter
DECLARE-RUNTIME-CYCLE	A legitimate feedback loop lacks bounds, ownership, or observability
DEFER	Evidence is missing, contradictory, or too noisy to justify movement

Rapid may finish only with PLACE, KEEP, DECLARE-RUNTIME-CYCLE, or DEFER. If a restructuring decision becomes plausible, record the candidate, set Analysis mode: Rapid → Full, and continue in Full. If the Full evidence is unavailable, remain in Full and emit DEFER with the missing proof in Next action.

Apply these growth rules:

• Attach a new component to the nearest semantically coherent parent whose public contract can own the relationship.
• Preserve sibling symmetry by default; specialize only when lifecycle, constraints, or measured pressure differ.
• Split along the axis that explains the strongest independent clusters: domain, abstraction tier, or layer.
• Prune an edge only after checking reachability, callers, and relevant history.
• Retire a component through an explicit removal signal — deprecation marker, reachability proof, owner, and cleanup path — never by leaving it unreferenced.
• Prefer one explicit boundary over multiple peer-to-peer exceptions.
• Prefer a probationary acceptance with instrumentation over an indefinite DEFER when evidence is absent and reversibility permits; when measured evidence contradicts the change, DEFER stands.
• At Low reversibility, take the smallest reversible step first: introduce the boundary or adapter, then move behind it once the contract holds.
• When reversibility is Unknown, DEFER the end state but independently grade any smaller precursor that could safely establish the missing facts.
• Reassess after material domain, ownership, or deployment changes, and when component count, team count, traffic, or data volume changes by an order of magnitude.

7. Measure and Enforce

Before accepting MOVE, SPLIT, MERGE, or INTRODUCE-BOUNDARY: