Skip to content

Freshness: a section-bearing file gets a file-level grade that can contradict its own sections #2177

Open

Description

@jacobo-ortiz

TELOS.md is registered twice in the freshness system: once as a context file (graded from its frontmatter last_reviewed) and once as the source of per-section markers (graded per section). The two clocks are independent and can disagree.

Repro

  1. Run /interview and review some TELOS sections, bumping each with TelosFreshness.ts --bump <slug>.
  2. GET /api/freshness/summary still reports TELOS.md at its previous reviewed_age_days and the same grade.
  3. TelosFreshness.ts --json reports the sections you did not walk as stale.

Observed on a populated install: 10 of 15 sections overdue while the file itself reported 27 days and grade D, immediately after a review that bumped 4 sections.

Why bumping the file is not the fix

FreshnessSystem.md is explicit that last_reviewed must not be bumped without a real principal review, since "bytes changed" is not "a human looked". A 4-of-15 section walk is not a full-file review.

That leaves no honest value for the field on a file whose entire content is sections:

  • Not bumping leaves a permanent D on a file that is being reviewed regularly, section by section.
  • Bumping asserts a full-file review that did not happen, which is the exact failure mode the doc warns about.

Evidence

fileFreshnessFor() computes pct and grade solely from the file's own frontmatter last_reviewed against a per-file threshold. Section markers never enter the computation, and the per-file threshold is independent of the per-section thresholds, so the two can also disagree on when something is due.

Proposal

Either derive a section-bearing file's grade from its sections (for example, the largest days-over-threshold among them), or drop such files from the file-level registry and surface them through their sections only. Both give one clock per file instead of two.

Happy to send a PR if you have a preference between the two.

Activity

  1. danielmiessler commented on Oct 3, 2026

    @danielmiessler
    Owner

    Thanks @jacobo-ortiz. Confirmed: TELOS.md's file-level grade is still computed only from its own last_reviewed, so section reviews never move it, and you're right that bumping the file would assert a review that didn't happen. Choosing between grading from the sections and dropping the file from the file-level list changes what the board shows, so it's tracked as a design change and not a quick patch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions