docs(TELOS): reconcile IDEAL_STATE/CURRENT_STATE READMEs with the code + document the scoring contract

[christauff]

Hi Daniel — first, thank you for LifeOS. I've been running it daily and the Current→Ideal framing is genuinely the best articulation of this idea I've seen. This PR comes out of actually populating the life dimensions end-to-end for the first time, which surfaced a small documentation/code drift. Happy to reshape any of it to your taste.

The issue

The READMEs in USER/TELOS/IDEAL_STATE/ and USER/TELOS/CURRENT_STATE/ tell users to create files that UpdateLifeosState.ts and Pulse can't read.

Both READMEs say:

Health.md · Finances.md · Work.md · Relationships.md · Learning.md · Energy.md

But LIFEOS/TOOLS/UpdateLifeosState.ts reads:

{ id: "health",         file: "HEALTH.md" },
{ id: "money",          file: "MONEY.md" },
{ id: "freedom",        file: "FREEDOM.md" },
{ id: "creative",       file: "CREATIVE.md" },
{ id: "relationships",  file: "RELATIONSHIPS.md" },
{ id: "rhythms",        file: "RHYTHMS.md" },
{ id: "infrastructure", file: "INFRASTRUCTURE.md" },

Two independent failures stack:

1. Case. Health.md ≠ HEALTH.md on a case-sensitive filesystem, which is every Linux install.
2. Taxonomy. Work, Learning, and Energy don't exist in the code. The code's Freedom, Creative, Rhythms, and Infrastructure don't appear in the READMEs. The two describe different models of a life.

A Linux user who follows the docs exactly gets zero dimensions scored, silently, with no error. Pulse keeps rendering "No life-area dimensions populated yet" while their files sit right there in the directory.

The good news is the shipped templates are already correct — IDEAL_STATE/ contains HEALTH.md, MONEY.md, FREEDOM.md and friends. Only the READMEs are stale, and they appear to predate the seven-dimension model. (The IDEAL_STATE README also says the directory "ships empty except for this README" while sitting next to those seven templates.)

The undocumented part

The scoring contract isn't written down anywhere, so "drop files into IDEAL_STATE/" is currently an instruction to guess at a format. From the parser:

• IDEAL_STATE/<DIM>.md → pct = 100 − (TBD count × 10). Scores articulation: how completely you've said what "good" looks like.
• CURRENT_STATE/<DIM>.md → pct = (have + 0.5 × partial) / total, from literal status: have|partial|missing rows. Scores coverage, and overrides the ideal-state score.

That override is the subtle and important bit, and it bit me in a way I think is worth surfacing: I wrote a thorough CREATIVE.md ideal and it scored 90%, which pushed the ring to 70% — while I was in fact doing almost none of it. A well-written ideal you aren't living still scores high. Writing the CURRENT_STATE file is what makes the dashboard honest (mine dropped to 30%, which was the true number). That behavior is correct and rather elegant, it just isn't discoverable without reading the parser.

Changes

• Both READMEs list the seven UPPERCASE filenames the code actually reads, with an explicit case-sensitivity note.
• Both document the scoring contract, including the status: row syntax and the override semantics.
• Added the five missing CURRENT_STATE templates (MONEY, FREEDOM, CREATIVE, RELATIONSHIPS, RHYTHMS) so both directories carry all seven dimensions. CURRENT_STATE/ previously shipped only HEALTH and INFRASTRUCTURE.

Docs and templates only. No code, no behavior change.

One thing I left alone

Both READMEs, and Pulse's empty state, point users at /interview — "run /interview and pick the Ideal State phase." The Interview skill's workflows are ContextCheckin, Phase0Setup, and TelosCheckin; there's no ideal-state or current-state phase, so that instruction currently dead-ends.

I didn't touch it, since how that flow should work is a design call that's yours to make. If it'd be useful, I'm glad to follow up with a PR adding those workflows — just say the word and I'll build it to whatever shape you prefer.

Thanks again. Happy to revise anything here.

[danielmiessler]

Thanks @christauff — this caught a real asymmetry, not just a docs gap. CURRENT_STATE/ shipped only 2 of the 7 dimension templates that IDEAL_STATE/ already had, so a fresh install scored ideal articulation with no current-coverage counterweight for five dimensions — a dashboard that flatters, exactly as your README rewrite puts it.

Ported into source. The public repo is generated at release, so I applied your changes to the private template source: the five new CURRENT_STATE templates (CREATIVE, FREEDOM, MONEY, RELATIONSHIPS, RHYTHMS) and both rewritten READMEs. CURRENT_STATE now mirrors IDEAL_STATE exactly (7 dimensions).

Before merging the doc intent I verified your scoring contract against the actual scorer (UpdateLifeosState.ts) — all four claims match the code:

• coverage = (have + 0.5 × partial) / total × 100
• literal status: have|partial|missing parsing
• a present CURRENT_STATE file overrides the IDEAL_STATE articulation score
• articulation = 100 − TBD × 10, clamped

So the README now documents what the code actually does. Closing since it's in the source; ships next release. Credited in the commit.