Docs contradict code: USER/TELOS/README.md documents the legacy split-file layout and never mentions TELOS.md

[nbost130]

Summary

LifeOS/install/USER/TELOS/README.md documents the legacy per-topic file layout as if it were current, and never mentions TELOS.md at all. TELOS.md in the same directory explicitly declares those files superseded, and the code agrees with TELOS.md.

The result: a reader who trusts the README concludes the unified TELOS.md is wrong. That's exactly what happened to me.

The contradiction, in one directory

USER/TELOS/README.md — its "Files" table presents the split files as the layout:

File	What goes in it
MISSION.md	The 1–3 things you're putting your life behind...
GOALS.md	Concrete year-scale goals tied to each mission...
BELIEFS.md	The opinions and frames you operate from...

TELOS.md does not appear in that table, or anywhere else in the README.

USER/TELOS/TELOS.md — same directory, final line:

"This file is the canonical TELOS. The DA and Pulse read it directly; the split files in this folder (MISSION.md, GOALS.md, …) are legacy samples that will be superseded as you fill in your real TELOS via the interview."

The code sides with TELOS.md

LifeOS/install/LIFEOS/TOOLS/GenerateTelosSummary.ts:

// Map legacy filename → H2 section name in unified TELOS.md.
// LIFEOS/USER/TELOS/TELOS.md is the single source of truth as of 2026-05-01;
// the per-file reads here fall back to that section when the legacy file
// is absent.
const LEGACY_FILE_TO_SECTION: Record<string, string> = { ... }

LifeOS/install/LIFEOS/TOOLS/TelosFreshness.ts:

const TELOS_PATH = join(LIFEOS_DIR, "USER", "TELOS", "TELOS.md");

Both read the unified file and parse its ## sections. The README is the odd one out.

Why this is worth fixing

The split files still ship in install/USER/TELOS/, so a fresh install contains both layouts, with the README pointing at the deprecated one. A user (or an AI assistant reading the repo, which is rather the point of LifeOS) will reasonably conclude that per-topic files are the standard and that a correctly-unified TELOS.md is a misconfiguration.

Concretely: I consolidated my 18 per-topic TELOS files into the unified TELOS.md, which was correct. My DA later read the README, plus a stale internal schema doc making the same claim, and told me my TELOS was a non-conformant fork that needed migrating back. It cost a couple of hours before I checked the source and found the code and TELOS.md had been right all along.

Suggested fix

1. Rewrite USER/TELOS/README.md so its Files table leads with TELOS.md as the single source of truth, describes the ## H2 sections as the units, and documents the <!-- updated: YYYY-MM-DD by:who --> per-section freshness markers that TelosFreshness.ts parses.
2. State plainly that MISSION.md / GOALS.md / BELIEFS.md / etc. are legacy samples retained for backward compatibility, and that they should not be re-split from the unified file.
3. Consider moving the legacy samples into a Legacy/ or Archive/ subdirectory so a fresh install shows one layout rather than two.

Happy to open a PR for the README rewrite if useful.

Environment

• Upstream: danielmiessler/LifeOS @ v7.1.1 (also present at v7.0.0)
• Files: LifeOS/install/USER/TELOS/README.md, LifeOS/install/USER/TELOS/TELOS.md, LifeOS/install/LIFEOS/TOOLS/GenerateTelosSummary.ts, LifeOS/install/LIFEOS/TOOLS/TelosFreshness.ts