fix(core): date undated okf-local sections from git history, not mtime

[siracusa5]

Problem

An OKF document with no updated: in frontmatter and no {updated=} heading attr resolved to the file mtime through a files layer and to null through an okf-local layer. Same bytes, two different sourceUpdated values, differing only by which adapter read them.

What this does

Rather than copy files.mjs's mtime into okf-local (the first attempt — see below), okf-local now dates undated sections from git history, which is what github.mjs already reports for the same bytes.

The rule, in order: explicit {updated=} attr → frontmatter updated → the file's last author date → the mtime, but only where no history can exist. Shared with files.mjs/github.mjs through withDocumentDate.

Why not mtime

Three independent adversarial reviewers blocked the mtime version, and they were right. Git does not preserve mtimes; a clone or a pull stamps the working tree with the operation time, and files that don't change afterward keep the clone date permanently. Verified: a doc committed 2024-03-01 and cloned today read as 2026-07-29. Through the resolver, a 2019-authored company doc dissented against a 2026-05-12 team decision carrying a date two months newer than the thing it disagreed with.

specs/contextcake-core/design.md:45-57 states the thesis verbatim — the updated-date is the staleness signal, replacing the hash-drift subsystem with "one honest glance." Mtime makes the glance lie, always in the fresher direction. Aggravating: renderCapture emits captured: and never updated:, so every capture concept took that path, and git-sync.mjs:83 requires the live team layer to be okf-local — maximum harm on the flagship flow.

The four ways this still got it wrong before landing

Each was found by review, fixed, and is now covered by a test that fails when the fix is reverted:

	Failure	Fix
Concurrency	The memo published an empty Map before its own await, so every reader arriving during the in-flight git log missed and fell back to mtime. mcp-server.mjs:253 does not await its request handler, so pipelined reads hit this deterministically — only the first caller got a real date.	Memoize the promise, not the map
Rebase	%cs is the committer date, and git-core runs pull --rebase as its standard divergence recovery, which rewrites committer dates to now — re-dating the whole bundle to today on the flow team-sync depends on.	%as (author date) survives a rebase
Shallow clones	The boundary commit lists the entire tree as added at the truncation date. service.mjs:539 clones --depth 1, so this was every repo added through the app.	Skip boundary commits; leave those sections undated
Unreadable history	A git log/ls-files failure inside a repo returned the same shape as "not a repo", so the file looked untracked and got the mtime — the branch violating its own documented invariant. ls-files did it silently.	inRepo distinguishes them; warn on both

Plus: a 30s TTL on the memo (a session-lifetime MCP server was serving the history it saw at boot), --relative instead of prefix arithmetic (a layer rooted in a subdirectory missed every lookup and silently fell back to mtime), a guarded statSync, and error.stderr || error.message in git-core so the new warnings don't render as cannot read commit dates ().

Also fixes a pre-existing UTC bug

toISOString().slice(0, 10) converts a local wall-clock event to a UTC calendar date, so a doc edited after 20:00 EDT reported tomorrow. Confirmed: a fixture written at 21:52 local resolved to 2026-07-29. Pre-existing at files.mjs:52 since #65; both adapters now format via localDate(). The tests derive their expected date from date rather than from the adapter's own formula, so they catch this class of bug instead of mirroring it.

Tests

resolver-test.sh gained a commit-dates step covering six shapes: repo root, subdirectory root, untracked doc, concurrent reads, shallow clone, and a git that fails inside a repo (via a PATH shim). Each was verified non-vacuous by reverting its specific fix and watching the matching assertion — and only that assertion — fail. files-source-test.sh keeps the cross-adapter parity check for the plain-folder case, where both adapters legitimately land on the mtime.

• npm test → exit 0, all 10 suites, also green under TZ=Pacific/Kiritimati (UTC+14) and TZ=Etc/GMT+12 (UTC-12)
• npm run build --prefix apps/site → exit 0
• Site demo data unchanged — every doc in apps/playground/demo-layers/ carries an authored updated:

Known costs, not fixed here

• Performance. git log --name-only -- . walks the whole history regardless of pathspec: measured 6ms → 3675ms on a 6335-commit repo, amortized by the 30s TTL but paid on the first read of each window. Reachable via "add local source" pointed at a large repo. A --max-count bound would cap it at the price of leaving old files undated; a HEAD-keyed disk cache would be better. Worth a follow-up.
• Merge-only changes and quoted/NFD filenames fall through to undated rather than wrong — the safe direction, but they are gaps.

🤖 Generated with Claude Code

[siracusa5]

Adversarial review — three independent reviewers, all three block

Ran three reviewers with different lenses (correctness / test-quality / design), each instructed to refute rather than approve. They converged independently on the same blocking finding.

BLOCKING — the mtime fallback inverts the staleness signal for okf-local

Git does not preserve mtimes. An okf-local layer is defined as "a git repo of OKF markdown" (okf-local.mjs:2, CLAUDE.md), so for this adapter the mtime is essentially never the authorship date — a clone or a pull stamps the working tree with the operation time, and files that don't change afterward report the clone date permanently.

Verified end-to-end on this branch. A doc committed 2024-03-01, cloned today:

mtime       = 2026-07-29   ← what okf-local now reports
last commit = 2024-03-01   ← what github.mjs reports for the same bytes

Through the resolver, a 2019-authored company doc dissenting against a team decision dated 2026-05-12:

"sourceUpdated": "2026-05-12",
"conflicts": [ { "layer": "company", "updated": "2026-07-29", ... } ]

The 2019 doc now reads as two months newer than the team's real decision. specs/contextcake-core/design.md:45-57 states the thesis verbatim — "the updated-date is the staleness signal … this replaces the entire hash-drift / shadow-detection subsystem with one honest glance." This makes that glance lie, in the one comparison the product exists to make. The error is always directional: it claims fresher, never staler.

Aggravating factors found by the reviewers that I had not weighted:

• renderCapture (capture.mjs:164-171) emits captured:, never updated: — so every capture concept in a live/team layer takes the mtime path. This is not a rare shape.
• git-sync.mjs:83 mandates that the live team layer be okf-local — the flagship team-sync path is the guaranteed-cloned path, so maximum harm lands where the product is sold.
• The payload contradicts itself: contributors[].updated is null (from frontmatter.updated, resolver.mjs:67) while that same layer's sourceUpdated is today (resolver.mjs:133). One resolve, one layer, two disagreeing fields. This fixed a cross-adapter disagreement by creating a cross-field one.
• mcp-server.mjs:633 already had a designed representation for "unknown date" — (updated ?). This makes it unreachable for okf-local and swaps honest ? for a confident wrong number.
• Shipped pack docs state the opposite contract. specs/contextcake-packs/…/writing-a-layer.md:32-35: "updated is not required by the engine but you should always set it — it is the entire staleness signal." Undated is supposed to mean unknown.

The premise is also weaker than the PR claims

resolver.mjs:133 already computes section.updated ?? c.updated ?? null, where c.updated is frontmatter.updated. So for okf-local the helper's first two rungs are a no-op — the resolver already produced that answer. The entire net effect of this change on okf-local is injecting the mtime. The PR body oversells it as restoring a fallback chain.

And the adapter asymmetry was arguably information, not inconsistency:

kind	date source	justified
files	mtime	yes — arbitrary folder, no VCS, mtime is the only signal
github	last commit	yes — the correct answer, and available
okf-local	mtime (this PR)	no — git-backed, so mtime is known wrong

Confirmed non-findings

The reviewers tried hard to break the rest and could not:

• The files.mjs refactor is behavior-preserving. Differential run of old inline logic vs withDocumentDate across a 9x4 matrix of frontmatter values x document dates: identical except documentDate === undefined (old undefined, new null), which no caller reaches — files.mjs:53 always passes a string, github.mjs:169-183 returns string | null. resolver.mjs:133 collapses both anyway.
• fs.statSync adds no new throw path. readFileSync already threw first in every non-race case (EISDIR, EACCES, dangling symlink). Only a new TOCTOU window, same class as the pre-existing existsSync→readFileSync one.
• No merge decision changes. orderContributors ties on frontmatter updated; sectionBeats is level-only; conflict emission filters on content; git-sync.mjs decay uses frontmatter.captured; whats_new uses frontmatter.updated. Blast radius is confined to sourceUpdated and conflicts[].updated.
• No golden-output breakage. fixtures/mcp-tools-baseline.json is schemas, not output.
• The new test is not flaky. Both statSync calls read the same stored inode mtime and toISOString() is timezone-independent, so UTC-midnight crossing, coarse granularity, TZ, and CI checkout timing cannot desynchronize them. No fixture pollution either — undated enters step 3's id list but no later assertion depends on count, ordering, or set membership.
• withDocumentDate is idempotent. withDocumentDate(withDocumentDate(p, "2026-01-01"), "2026-07-28") → 2026-01-01. No double-application trap.
• Engine stays dependency-free.

Separate pre-existing bug found in passing

mtime.toISOString().slice(0, 10) converts a local wall-clock event to a UTC calendar date, so a doc edited after 20:00 EDT reports tomorrow's date. Confirmed: a fixture written at 21:52 local resolved to 2026-07-29. This is pre-existing at files.mjs:52; this PR extends it to okf-local. The new test cannot catch it because it computes its expectation with the identical formula. Worth its own fix (use local date components) regardless of what happens to this PR.

Options

• A — drop the mtime rung from okf-local, and invert the new test to assert the asymmetry is deliberate, with a comment explaining why. Cost ≈ zero; restores honest ? rendering. This is the pre-PR behavior, now documented rather than accidental.
• B — use the last-commit date for okf-local (matches github.mjs; runGit is already exported from git-core.mjs:35, so no new dependency). The honest version of parity. Costs: mcp-server.mjs sweeps loadConcept over every id at 325/369/429/474/512, so it needs github.mjs's memo pattern (one batched git log --name-only --format=%cs, cached per generation) or a search becomes N subprocess spawns; and okf-local roots aren't required to be git repos, so it still needs a null fallback underneath. Deserves its own commit.
• C — merge as-is, accepting that undated okf-local docs display checkout time.

Holding the merge pending a call on these.