Skip to content

docs/ARCHITECTURE.md directory tree incorrectly places GOALS.md and GOALS_OPERATIONAL.md inside data/ #6032

Description

@atomantic

Problem

In docs/ARCHITECTURE.md:99-150, the directory tree depicts GOALS.md and docs/GOALS_OPERATIONAL.md as children of data/:

├── data/                      # Runtime file data (gitignored) — relational records live in PostgreSQL (see docs/STORAGE.md)
│   ├── apps.json              # Registered apps (read by autofixer)
│   ├── providers.json         # AI provider configs
│   ├── history.jsonl          # Action history (JSON Lines)
│   ├── browser-config.json    # Browser CDP/health configuration
│   ├── TASKS.md               # User task file
│   ├── COS-TASKS.md           # System task file
│   ├── GOALS.md               # Repository mission and goals
│   ├── docs/GOALS_OPERATIONAL.md # Operational CoS goals

Neither file exists inside data/:

  • GOALS.md lives at the repository root (/GOALS.md).
  • GOALS_OPERATIONAL.md lives at /docs/GOALS_OPERATIONAL.md.

When PR #5255 unified data/COS-GOALS.md into the root GOALS.md and added docs/GOALS_OPERATIONAL.md, it updated the labels in docs/ARCHITECTURE.md without moving them out of the data/ subtree in the ASCII diagram.

Trigger

A contributor or agent inspecting docs/ARCHITECTURE.md to locate the repository mission or operational goals documents and attempting to read data/GOALS.md or data/docs/GOALS_OPERATIONAL.md.

Impact

Automated scripts, coding agents, or contributors attempting to resolve the documented paths encounter ENOENT.

Fix

  1. Update docs/ARCHITECTURE.md directory structure diagram:
    • Remove GOALS.md and docs/GOALS_OPERATIONAL.md from the data/ block.
    • Show GOALS.md at the repository root level.
    • Show GOALS_OPERATIONAL.md under docs/.

Alternative rejected: Creating symlinks under data/ — rejected because data/ is gitignored runtime data and should not house tracked repository documentation.

Acceptance Criteria

  • docs/ARCHITECTURE.md no longer lists GOALS.md or docs/GOALS_OPERATIONAL.md under data/.
  • docs/ARCHITECTURE.md accurately represents the locations of /GOALS.md and /docs/GOALS_OPERATIONAL.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationeffort:lowEffort: lowmodel:lightModel size: lightplanTracked by /do:replanplanner:gemini-3-7-flashPlan authored by the gemini-3-7-flash model

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions