Skip to content

Advanced: architecture drift

Based on: walkthrough WT-07 and the Memory specification’s reference case · Skills: Memory (check), then Implement or a decision revision · Status: illustrative, NOT_RUN

Goal

Section titled “Goal”

Two Memory entries may be out of date after manual changes:

  1. an approved decision (ADR-007) that says object mapping in the Orders module uses Mapperly only;
  2. an observation that points to a source file that has since moved.

Find out what is true now, without rewriting either record.

Concepts demonstrated

Section titled “Concepts demonstrated”
  • Project Memory: record types, per-entry freshness, read-only check.
  • Observation drift (STALE) versus decision conflict (Architecture Drift, CONFLICT).
  • Evidence strength: package reference versus actual usage.

Files involved (synthetic project)

Section titled “Files involved (synthetic project)”
File Role
.kiyo/memory/index.md Navigation by entry ID
.kiyo/memory/decisions.md Entry MEM-DEC-0007 (approved decision)
.kiyo/memory/architecture.md Entry MEM-ARCH-0003 (observation)
src/Orders/Mapping/OrderMappingProfile.cs AutoMapper profile found during the check
src/Orders/Orders.csproj Package references

The Memory records

Section titled “The Memory records”
.kiyo/memory/decisions.md (illustrative)
## MEM-DEC-0007 — Object mapping uses Mapperly


- id: MEM-DEC-0007
- record_type: decision
- status: APPROVED
- statement: The Orders module maps DTOs with Mapperly only.
- source: approved record; docs/adr/ADR-007-object-mapping.md
- observed_date: UNKNOWN
- last_modified: UNKNOWN
- last_verified: UNKNOWN
- verification_status: UNVERIFIED
- verification_scope: decision text only; call sites not inspected
- uncertainty: implementation conformance not yet checked
- repository_context: orders-service; component src/Orders; branch UNKNOWN
- git_revision: UNKNOWN
- approval_source: ADR-007
- approval_scope: src/Orders
.kiyo/memory/architecture.md (illustrative)
## MEM-ARCH-0003 — Order DTOs live in Contracts


- id: MEM-ARCH-0003
- record_type: observation
- status: ACTIVE
- statement: Order DTOs are defined in src/Orders/Contracts/OrderDtos.cs.
- source: code; src/Orders/Contracts/OrderDtos.cs
- verification_status: VERIFIED
- verification_scope: file existence and type names at an earlier revision

Request

Section titled “Request”

Select Memory, then:

Check these two Memory entries against this branch. Report factual corrections separately from decision conflicts; do not write.

Expected behavior

Section titled “Expected behavior”
  1. Resolve the canonical store (.kiyo/memory/) and the current branch, worktree, and component scope.
  2. Read the index and the two entries only.
  3. MEM-ARCH-0003: OrderDtos.cs is gone from Contracts/. A search within scope finds the same types in src/Orders/Dtos/OrderDtos.cs. Outcome: STALE, with a correction candidate that keeps the ID and history. If no replacement is found, the outcome is UNVERIFIED, and nothing is deleted.
  4. MEM-DEC-0007: inspect registrations and mapping call sites, not just packages. OrderMappingProfile.cs and IMapper.Map<> calls establish actual AutoMapper usage. Outcome: Architecture Drift. The decision is preserved.
  5. Write nothing: no status changes, no date refresh, no report file.

Expected report (illustrative)

Section titled “Expected report (illustrative)”
Drift report (excerpt)
| Entry / decision ID | Recorded claim and type | Current scoped evidence | Finding / proposed action |
| --- | --- | --- | --- |
| MEM-ARCH-0003 | observation: DTOs in Contracts/ | types now in src/Orders/Dtos/OrderDtos.cs | STALE → propose source path correction (sync) |
| MEM-DEC-0007 | decision (ADR-007): Mapperly only | AutoMapper profile + 6 IMapper.Map call sites | Architecture Drift → human decision required |


- **Decision ID:** MEM-DEC-0007 — ADR-007, scope src/Orders
- **Observed difference:** Deviation
- **Confidence:** HIGH — usage inspected; a package reference alone would be Insufficient evidence
- **Possible interpretations:** unauthorized drift; an approved exception not recorded
- **Required human decision:** align code with ADR-007, or revise ADR-007 through its approval process
- **Memory impact:** CONFLICT (known decision conflict takes precedence); UPDATE_REQUIRED pending for MEM-ARCH-0003
- **Status:** DONE — bounded check delivered; zero files written

Resolution paths

Section titled “Resolution paths”
Choice Next request
Fix the observation Memory sync: “Apply only the MEM-ARCH-0003 source path correction.”
Align the code Implement: “Replace AutoMapper usage in src/Orders with Mapperly per ADR-007; add mapping tests.”
Change the decision Revise ADR-007 through its owner; then record the revision with real approval provenance

Why it is structured this way

Section titled “Why it is structured this way”

If code could overwrite decisions, every accidental deviation would become the new architecture. If decisions could overwrite facts, Memory would lie about the code. Keeping observation corrections and decision conflicts in separate channels, with a human decision at the conflict, keeps both trustworthy.

Section titled “Related”