feat: no-historical-comments + no-bare-date-now

[agjs]

Summary

Two new rules covering categories of agent-generated drift the existing plugin set didn't catch.

eslint-plugin-comment-hygiene/no-historical-comments

Flags source comments that frame code relative to what it used to do or to a past incident:

• // Codex flagged X
• // before the fix / // after the fix
• // after the refactor / // the X refactor
• // we used to / // this used to / // used to be
• // no longer
• // kept for backwards compat
• // (was|were) a footgun/bug
• // historically
• // Alpine-era workaround

Source comments must describe the current invariant. History belongs in the commit message or PR description, pinned to the diff it describes — inline comments rot the moment the code changes again. JSDoc-style block comments are exempt.

eslint-plugin-code-flow/no-bare-date-now

Disallows direct non-deterministic time/random sources outside an allowlisted set of utility paths:

• Date.now()
• new Date() with zero args
• Date() with zero args
• Math.random()

Explicit-argument forms like new Date(1700000000000), new Date('2026-01-01'), and Date.parse(...) are unaffected (they're pure parsers, not clock reads).

Determinism is required for snapshot tests, workflow replays, time-travel debugging, and resumable jobs. Consumers route through a typed util that can be faked in tests; the util's path is exempted via the allowedPaths option:

{
  "code-flow/no-bare-date-now": [
    "error",
    { "allowedPaths": ["src/lib/time/", "src/lib/random/"] }
  ]
}

Why these two

Both came out of a real audit pass against an agent-built PR on a downstream consumer. The agent produced ~12 "Codex flagged", "before the fix", "after the refactor" comments that were caught by review but not by tooling. Separately, a determinism rule kept coming up as a near-miss when reviewing test failures rooted in stray Date.now() / Math.random() calls.

Tests

• comment-hygiene: 28 → 50 (+22 new for no-historical-comments)
• code-flow: 80 → 102 (+16 new for no-bare-date-now; +6 plugin-shape updates)
• Builds clean on both packages

Release plan

Standard changeset flow — .changeset/no-historical-comments.md and .changeset/no-bare-date-now.md bump each plugin minor. Merging this PR opens the "Version Packages" PR; merging that publishes to npm.

🤖 Built with Claude Code