Architecture Maps Need Authority Labels

A system map is only useful when it tells future workers which paths are authoritative, supported, legacy, deprecated, observational, or unsafe to extend.

The Surface Problem

The surface problem looked like missing documentation.

There were several command paths, scaffolding paths, wrappers, and observation surfaces living beside each other. A future worker could see all of them, but the system did not clearly say which path carried lifecycle authority, which path was only a convenience facade, which path existed for historical reasons, and which path should not be extended.

That is not just a documentation gap. It is a governance gap.

The Real Problem

When a system has multiple ways to do similar work, the map is part of the control surface.

If the map is missing, people infer authority from visibility. If the map is wrong, people extend the wrong surface with confidence. If the map is too vague, every future change has to rediscover the boundary before it can proceed safely.

The real problem was not that the architecture had rough edges. It was that the rough edges were not labelled in a way future work could safely use.

What Was Discovered

The work found three useful distinctions.

First, documenting architecture and cleaning architecture are different jobs. A bounded reference can make existing complexity visible without pretending to resolve it.

Second, documentation can become enforcement when it is added to prompts, checklists, or early-stage review surfaces. At that point, it is no longer merely explanatory. It shapes future decisions.

Third, semantic accuracy matters more than heading coverage. It is not enough for a reference to contain the right sections. It must tell the truth about authority, support level, lifecycle role, and removal risk.

What Changed

The useful change was structural but bounded.

The system gained an architecture reference that labelled command and path categories according to their real authority. Early review surfaces were updated to require architecture-reference checks before future work made material changes. Tests were added around those prompt expectations.

The work deliberately did not refactor the command paths, centralize state mutation, change routing behavior, or clean up legacy surfaces. That restraint mattered. The goal was to make the map accurate before changing the territory.

Why It Matters

Architecture references are deceptively risky because they look passive.

In practice, a reference is often how future workers decide where to add behavior, where to avoid edits, and which path represents the system's intended direction. If the reference overstates an old path, understates the canonical path, or blurs an observational surface into an authority surface, it can turn confusion into policy.

The safer pattern is to label paths by authority and lifecycle role:

• canonical authority
• supported facade
• scaffold primitive
• legacy but still present
• deprecated
• observational only
• removal candidate
• unsafe to extend

Those labels let future work move faster without guessing.

The Reusable Lesson

Architecture maps need authority labels.

Before a team cleans up a complex system, it often needs a truthful map of the current system. That map should distinguish current truth from intended direction, convenience from authority, and legacy presence from future endorsement.

The map should also be verified semantically. A string search can prove that words exist. It cannot prove that the document preserves the right authority boundary.

Better Pattern

Use architecture references as governed artifacts, not as casual documentation.

For material workflow systems:

1. Enumerate the live paths from repo or system truth.
2. Label each path's authority, support level, and lifecycle role.
3. Separate current behavior from intended direction.
4. Name legacy and deprecated paths without fixing them in the same change.
5. Add review checks where future work is likely to touch those boundaries.
6. Verify the meaning of authority claims, not only the presence of headings.

Related Concepts

• Artifact contracts
• Prompt guardrails
• Workflow governance
• Semantic verification
• Authority boundaries
• Documentation and knowledge capture