Skip to content

ADR-0003 — Operating model must name logical authorities, not filesystem paths

  • Status: Accepted
  • Date: 2026-06-29
  • Related: ADR-0002 (runtime baseline), standards/engineering-standard.md §Portability, operating-model/platform-integration-engineer.md

Finding

Hard-coded workstation paths were discovered in the operating model — including in governance artifacts authored during this session (ADR-0002, the Platform Integration operating model). The Authority Plane resolver blu work current itself emits a hard-coded home-directory path for the ownership map, and BluTown/ledgers/ no longer exists.

Classification

Portability defect. Not a stale-path bug. The operating model became coupled to one developer's workstation: /Users/<name>/… is one machine's realization of the architecture, not the architecture. A disappearing local directory is the symptom; the defect is that an absolute path was allowed to stand in for a logical authority.

Impact

  • Multi-developer onboarding (different username / checkout layout breaks the docs)
  • Remote agents and CI runners (no such home directory)
  • Oracle runtime (different filesystem entirely)
  • Future workspace moves

Resolution

Replace path references with logical authorities that the workspace runtime resolves. Each authority is named in governance and resolved by environment/workspace config:

  • Ownership / Tool Map → owned by the Engineering Standard authority; resolved via the existing BLU_* env / workspace-canonical discovery pattern. Precedent already exists in the same CLI: blu agents "reads path from BLU_AGENTS_PATH or workspace canonical." The defect is that blu work current did not follow that pattern. Reusing the existing pattern is composition, not new code.
  • Assignment Queue → Beads, resolved via bd where / BEADS_DIR discovery (Gas Town Hook).
  • Capability Registry / Objective Registry → Gas City + Oracle, read via gt / blu remote.

The permanent rule is recorded in standards/engineering-standard.md §Portability: Architecture names logical authorities. Runtime resolves them. Filesystems merely host them.

Status

Classified only — no implementation yet. Per operator instruction, work stops after classifying the defect and identifying the logical authorities. The runtime-resolution change to blu work current (make the ownership-map lookup follow the BLU_AGENTS_PATH/workspace-canonical pattern instead of a home-dir path) is a named follow-up owned by the blu-cli repo, not done here.

Consequences

  • ADR-0002's blocker #2 is reframed: the action is not "operator names a replacement path." It is "the ownership map is resolved by the Engineering Standard authority via workspace/env discovery." No absolute path is to be added anywhere.
  • Every governance document must pass the onboarding test before merge.