Architecture Freeze: When to Lock Down a Cognitive Substrate and Why

Milestones M2.5 through M4D had implemented the full cognitive substrate: event log, cycle driver, contributor/attention framework, Character, Relationship, Interpretation, Presence, Reflection, Learning, Planning, Execution, Operating Environment, Measurement, Intent Engine, and World State. Each milestone was tested and certified.

Immediately after M4D, a full red-team architecture audit was conducted against the actual implementation — not a design review, but direct code inspection with the instruction "assume your job is to break the architecture." Six critical issues were found and fixed:

1. Nondeterministic event/artifact ordering inside concurrently-scheduled contributor batches
2. An accepted ADR (0078) with zero implementing code
3. An unguarded exception path that failed an entire cognitive cycle instead of degrading safely
4. A relationship-graph write race with no way to retract a stale edge
5. A fully-generated labeled dataset with no benchmark consuming it
6. Zero automated regression detection despite ADR 0076's explicit promise of one

A second pass closed three latency/scalability findings. A cleanup pass removed three confirmed-dead packages and one dead query method.

Then the freeze was declared.

When is the right time to declare a cognitive substrate "complete" and lock it against structural change?

The freeze was not arbitrary or convenient. The specific bar cited in ADR 0082:

"Not 'the architecture was designed carefully' — every prior ADR already claims that — but 'the architecture was adversarially audited against its own implementation, on the day of this freeze, and every finding from that audit that rose to the level of a real defect was fixed and verified — not deferred, not rationalized.'"

What the freeze means:

The freeze entered maintenance mode for the 17 frozen packages. Maintenance mode permits unconditionally:

• Bug fixes
• Performance work (measured, not guessed)
• Test coverage additions
• Documentation corrections
• Dependency/security patching

What maintenance mode does not permit without an ADR:

• A new package
• A new ContributorPhase
• A new EventKind
• A new persisted store or database singleton
• A change to CLAUDE.md's invariants

Why this specific moment:

M5 (Multimodal & Ambient) was next. Its purpose: Ashi "perceives beyond text and becomes present rather than invoked" — continuous, ambient, proactive behavior with less per-turn human confirmation than anything built before. This is the riskiest milestone in the roadmap.

Building the riskiest milestone on an unverified foundation — a substrate whose correctness properties (determinism, replayability, safe degradation, regression signal) had not been verified until this week — would be building the hardest problem on the weakest foundation.

The freeze guaranteed that when M5 shipped bugs (it did — see Content Piece 017), those bugs were M5 bugs, not substrate bugs. The substrate was verified; any new failure was new work.

The ADR criteria for breaking the freeze:

An ADR is required for new structural work. The ADR must include:

1. A filed, reproducible bug (not a design preference)
2. A demonstrated capability gap (evidence-backed, not speculative)
3. A performance measurement (not a guess)

"We think it would be cleaner" does not meet the bar. "There is a cycle in the package graph that causes test failures" does (ADR 0148 broke the freeze to fix the execution/planning/reflection cycle).

• docs/decisions/0082-architecture-freeze.md — full freeze ADR
• pre-m5-substrate-freeze git tag — the exact commit
• docs/decisions/0148-execution-planning-reflection-cycle-resolution.md — example of a valid freeze break
• CLAUDE.md — "Architecture Freeze" section, "What requires an ADR" list

The freeze's value is not in preventing change — it is in requiring evidence before change. "We could add a new package for this" is easy to rationalize in the moment. "Show me the filed bug or demonstrated capability gap" is harder to satisfy and therefore only happens when the change is genuinely necessary.

The audit-first approach to the freeze (adversarial code inspection before declaring frozen) is what made the freeze meaningful: it was not declaring "we're done" as a planning convenience but as an evidence-based statement that the substrate had been inspected under adversarial conditions and found sound.

The freeze also serves as a forcing function for discipline: when everything is in maintenance mode, the question for any proposed change shifts from "should we add this?" to "does the evidence demand this?". That is a higher bar, and it is the right bar for a substrate that other systems depend on.

The red-team audit should have been conducted after each major milestone, not only before M5. The six findings in the M4D post-audit included items that had been present (and valid issues) for multiple milestones. An earlier audit would have found them earlier.

A software architecture freeze is a tool for focus, not a claim of perfection. Its value is in creating a stable foundation for higher-risk work on top of it. The bar for freezing should not be "the design is complete" but "the implementation has been adversarially verified against the design."

Any freeze criterion must be testable: "no new package without an ADR" is testable (count the packages, check the ADRs). "The design is good" is not testable. Make the criteria mechanical so the freeze can be enforced even under time pressure.

• docs/decisions/0082-architecture-freeze.md
• docs/decisions/0148-execution-planning-reflection-cycle-resolution.md
• docs/decisions/0147-evidence-confidence-extraction.md
• CLAUDE.md — "What requires an ADR" section
• pre-m5-substrate-freeze git tag