okf frontmatter: 59-doc stale baseline and the freshness-window decision #5

New issue

Closed

opened 2026-10-04 18:50:08 +02:00 by clawdie · 0 comments

clawdie commented

2026-10-04 18:50:08 +02:00

Owner

okf frontmatter: 59-doc stale baseline and the freshness-window decision

Summary

The okf-frontmatter gate is red on main: 59 tracked markdown files share
last_verified: 2026-08-02 and the window is 30 days. The gate is not
change-scoped and runs in CI on every pull request and push, so it blocks
unrelated work. A change-scoped fix is in flight on branch
docs/cross-repo-conventions (clawdie-iso, unmerged); the repository-wide
baseline still needs a decision and a verified refresh.

Evidence

./scripts/check-okf.sh -> PASS: 62 FAIL: 59.
Every failing file carries last_verified: 2026-08-02 — a single bulk stamp
that has never been refreshed.
Categories: doc/ 16, docs/ 15, docs/plans/ 7, skills/* several, plus
README.md, REQUIREMENTS.md, TESTING.md, runner/README.md,
scripts/poudriere/README.md.
Window is hardcoded to 30 days (scripts/check-okf.sh:25); colibri uses
OKF_MAX_AGE_DAYS default 90.
CI: .forgejo/workflows/format-check.yml runs check-okf.sh --strict on
pull_request and push:[main].

Mitigation in flight (branch, unmerged)

scripts/check-okf.sh gains --changed / --base REF (full scan remains the
default).
format-check.yml runs the changed-doc gate for PRs and pushes, with
fetch-depth: 0.
New .forgejo/workflows/okf-staleness-report.yml runs the full scan weekly,
advisory and non-blocking.
Window unchanged; no dates refreshed.

Decisions needed

Freshness window: keep 30 days, or adopt colibri's 90? The cross-repo
convention currently records this as TBD - operator decision.
Refresh strategy: per-document verified update, or archive/relocate stale
planning docs first (doc/ + docs/plans/ = 23 of 59 files)?
Retain the full check-okf.sh --strict as an explicit release check (not
per-PR)?

Do not

Bulk-stamp last_verified without verifying content; that hides the staleness
the gate exists to detect.

Refs: clawdie-iso scripts/check-okf.sh, .forgejo/workflows/format-check.yml,
branch docs/cross-repo-conventions; colibri scripts/check-okf.sh
(--changed, OKF_MAX_AGE_DAYS).

# okf frontmatter: 59-doc stale baseline and the freshness-window decision ## Summary The okf-frontmatter gate is red on `main`: 59 tracked markdown files share `last_verified: 2026-08-02` and the window is 30 days. The gate is not change-scoped and runs in CI on every pull request and push, so it blocks unrelated work. A change-scoped fix is in flight on branch `docs/cross-repo-conventions` (clawdie-iso, unmerged); the repository-wide baseline still needs a decision and a verified refresh. ## Evidence - `./scripts/check-okf.sh` -> `PASS: 62 FAIL: 59`. - Every failing file carries `last_verified: 2026-08-02` — a single bulk stamp that has never been refreshed. - Categories: `doc/` 16, `docs/` 15, `docs/plans/` 7, `skills/*` several, plus `README.md`, `REQUIREMENTS.md`, `TESTING.md`, `runner/README.md`, `scripts/poudriere/README.md`. - Window is hardcoded to 30 days (`scripts/check-okf.sh:25`); colibri uses `OKF_MAX_AGE_DAYS` default 90. - CI: `.forgejo/workflows/format-check.yml` runs `check-okf.sh --strict` on `pull_request` and `push:[main]`. ## Mitigation in flight (branch, unmerged) - `scripts/check-okf.sh` gains `--changed` / `--base REF` (full scan remains the default). - `format-check.yml` runs the changed-doc gate for PRs and pushes, with `fetch-depth: 0`. - New `.forgejo/workflows/okf-staleness-report.yml` runs the full scan weekly, advisory and non-blocking. - Window unchanged; no dates refreshed. ## Decisions needed 1. Freshness window: keep 30 days, or adopt colibri's 90? The cross-repo convention currently records this as `TBD - operator decision`. 2. Refresh strategy: per-document verified update, or archive/relocate stale planning docs first (`doc/` + `docs/plans/` = 23 of 59 files)? 3. Retain the full `check-okf.sh --strict` as an explicit release check (not per-PR)? ## Do not Bulk-stamp `last_verified` without verifying content; that hides the staleness the gate exists to detect. Refs: clawdie-iso `scripts/check-okf.sh`, `.forgejo/workflows/format-check.yml`, branch `docs/cross-repo-conventions`; colibri `scripts/check-okf.sh` (`--changed`, `OKF_MAX_AGE_DAYS`).

clawdie referenced this issue

2026-10-04 19:37:00 +02:00

docs(agents): cross-repo pointer + change-scoped okf gate #6

clawdie closed this issue

2026-10-15 08:20:28 +02:00

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

clawdie/clawdie-iso#5

No description provided.

Rows
Columns