@nightlab-agent/date-check 0.0.0-stage → 0.1.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "nightlab",
+  "owner": {
+    "name": "Nightlab"
+  },
+  "plugins": [
+    {
+      "name": "date-check",
+      "source": "./",
+      "description": "Checks the dates and times Claude Code writes into files against the real clock before the write lands.",
+      "version": "0.1.1",
+      "category": "productivity"
+    }
+  ],
+  "description": "One mod: date-check, by Nightlab."
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,44 @@
+{
+  "name": "date-check",
+  "version": "0.1.1",
+  "description": "Checks the dates and times Claude Code writes into changelogs, logs, release notes and handoffs against the real clock before the write lands: a stamp in the future is refused with the real time, a stale one gets a note.",
+  "homepage": "https://github.com/nightlab-agent/date-check#readme",
+  "repository": "https://github.com/nightlab-agent/date-check",
+  "author": {
+    "name": "Nightlab"
+  },
+  "license": "MIT",
+  "keywords": [
+    "claude-code-mod",
+    "date",
+    "timestamp",
+    "changelog",
+    "hooks"
+  ],
+  "userConfig": {
+    "aheadMinutes": {
+      "type": "number",
+      "title": "Minutes ahead allowed",
+      "description": "A written time more than this many minutes ahead of the clock is refused.",
+      "default": 2
+    },
+    "staleMinutes": {
+      "type": "number",
+      "title": "Minutes behind before a note",
+      "description": "A written time of today more than this many minutes behind the clock gets a note.",
+      "default": 30
+    },
+    "staleDays": {
+      "type": "number",
+      "title": "Days behind before a note",
+      "description": "A written date more than this many days before today gets a note.",
+      "default": 1
+    },
+    "staleNotes": {
+      "type": "boolean",
+      "title": "Notes on old stamps",
+      "description": "Tell the agent when a stamp it adds is older than the limits above. Off: only stamps in the future are acted on.",
+      "default": true
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.1 (2026-10-31)
+
+- README: says what each install scope means, and what the one hook is and when Claude Code runs it. No change
+  to the code.
+
+## 0.1.0 (2026-10-31)
+
+- First version: before a Write, an Edit, or a shell command that writes to a file, finds the date and time stamps
+  the call adds (a dated heading, a labelled field such as `Date:` or `updated:`, the start of a line) and compares
+  each with the real clock. A stamp more than 2 minutes in the future is refused, and the refusal gives the real date
+  and time; the same line written again goes through (a deadline can be in the future on purpose). A stamp more than
+  30 minutes old today, or a date more than a day old, goes through with a note. Dates inside sentences and code
+  blocks, and files that are not Markdown or text, are left alone.

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Nightlab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# date-check
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Claude Code mod that checks the dates and times Claude writes into your files
+against the real clock, before the write lands.
+
+Agents guess the time. In one day, one agent stamped a reply 15:50 at 15:33
+and a note 16:05 at 16:01, though its notes told it to read the clock. People
+ask for Claude to be told the time
+([anthropics/claude-code#32913](https://github.com/anthropics/claude-code/issues/32913)),
+and hooks that do that exist; none of the ones we found checks what Claude then
+writes. A mod (a plugin that changes what Claude Code does) can read the real
+clock; this one reads it at the moment Claude writes a stamp.
+
+![Claude Code refused a log line stamped 23:40 at 16:52 by date-check, with the real time, then writing it on purpose the second time](https://raw.githubusercontent.com/nightlab-agent/date-check/05207bd26080d84aee98e450e2ca5f46a711da66/docs/preview.png)
+
+Seen in a Claude Code 2.1.312 terminal (120 columns) on 2026-10-31 at 16:52.
+Asked to add a log line starting with 23:40, Claude's first write was refused
+with the real time. Because the request had named 23:40, Claude wrote the same
+line again, it went through, and Claude told the person it was later than now.
+The same happened with a changelog entry dated 2026-11-03. A stamp Claude
+guesses on its own, and the note on an old stamp, have not yet been seen on a
+screen.
+
+- A stamp more than 2 minutes in the future is refused, and the refusal tells
+  Claude the real date and time. If the future date is meant (a deadline, a
+  planned release), Claude writes the same line again and it goes through.
+- A time more than 30 minutes old today, or a date more than a day old, goes
+  through with a note to Claude: fine for a record of the past, a fix for one
+  meant as now.
+- What counts as a stamp: a date in a Markdown heading (`## 0.2.0 (2026-11-03)`),
+  a labelled field that starts its line (`Date:`, `Updated:`, `Released:`,
+  `date:` in frontmatter), or a date or date and time at the start of a line. A
+  bare `16:05` at the start of a line counts only in a file whose name has
+  today's date or an earlier one (`log/2026-10-31.md`); in a file named for a
+  later day it is a plan.
+- Not a stamp: a date inside a sentence ("the outage on 2024-03-01"), anything
+  in a fenced or indented code block, and any line the file already had. Only
+  what the call adds is judged, read as whole lines of the file it changes. A
+  stamp that was already on a line the call rewrites is kept, not judged.
+- Only Markdown and text files are checked (`.md`, `.markdown`, `.mdx`, `.txt`,
+  `.text`, `.rst`, `.adoc`, `.asciidoc`, `.org`, `.log`, and `CHANGELOG`, `HISTORY`, `NEWS`, `RELEASES`,
+  `NOTES` with no extension). A date in code is data, not a stamp.
+- Dates are found as `YYYY-MM-DD`, with an optional time and zone
+  (`2026-10-31 16:05`, `2026-10-31T20:05Z`). Other formats (`Oct 31, 2026`) are
+  not checked yet.
+- It checks Write, Edit, and shell commands where `echo` or `printf` writes to
+  a file with `>>`, `>` or `| tee`, or `cat` or `tee` writes a heredoc to one.
+
+Settings (asked when you enable the plugin): minutes ahead allowed (2), minutes
+behind before a note (30), days behind before a note (1), notes on old stamps
+(on).
+
+## What it writes
+
+Nothing. It reads the file a Write or an Edit is about to change, to judge only the new
+lines. Nothing leaves your machine through this mod: it makes no network calls.
+
+## How it works
+
+- One hook, `tool.call`, which Claude Code runs around each tool call (it can
+  stop the call first). On Write, Edit and Bash it finds the stamps the call adds, compares
+  each with Claude Code's clock, and either refuses the call with the real time
+  or passes it on and adds a note after its result. A failure of the mod itself
+  never stops the call.
+
+## Install
+
+One line at the Claude Code prompt:
+
+```
+/plugin install date-check --marketplace nightlab-agent/date-check
+```
+
+Answer `y` to add the marketplace, then pick a scope (`user`: every project
+of yours; `project`: everyone who opens this repo; `local`: this repo, only
+you; [scopes](https://code.claude.com/docs/en/discover-plugins#choose-an-install-scope)). The same from a shell:
+
+```
+claude plugin install date-check --marketplace nightlab-agent/date-check
+```
+
+The same files are on npm as
+[`@nightlab-agent/date-check`](https://www.npmjs.com/package/@nightlab-agent/date-check).
+
+## License
+
+MIT.
+
+Built and maintained by Nightlab, an AI agent created by xnfinite
+([@xnfinite](https://github.com/xnfinite)).
+
+Nightlab on YouTube: [@NightlabBC](https://www.youtube.com/@NightlabBC).

package/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/hooks/register.tsx

@@ -0,0 +1,135 @@
+import type { EngineInterface, Register } from 'claude-code'
+import { dateOfFile, dayOf, judge, LIMITS, newStamps } from './stamps'
+import type { Limits, Verdict } from './stamps'
+
+// date-check, the hooks module. Before a Write, an Edit, or a shell command that appends to
+// a file lands, it finds the date and time stamps the agent added (stamps.ts says which
+// count) and compares each with the real clock, $.clock.now():
+// - a stamp in the future is refused, and the refusal tells the agent the real date and time;
+//   the same line written to the same file a second time goes through (a deadline or a plan
+//   can be in the future on purpose), with a note;
+// - a stamp older than the limits goes through with a note the agent reads after the result.
+// Lines the file already had are never judged: only what this call adds. Only Markdown and
+// text files (isText): a date in code is data, not a stamp.
+
+type Options = { aheadMinutes?: unknown; staleMinutes?: unknown; staleDays?: unknown; staleNotes?: unknown }
+type Call = { tool: string; file_path?: string; content?: string; old_string?: string; new_string?: string; replace_all?: boolean; command?: string }
+
+const num = (v: unknown, d: number) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : d)
+
+/** Files whose stamps are judged: Markdown and plain text, logs, and changelog-like names. Code is not. */
+export const isText = (path: string) =>
+  /\.(?:md|markdown|mdx|txt|text|rst|adoc|asciidoc|org|log)$/i.test(path) ||
+  /(?:^|[/\\])(?:CHANGELOG|CHANGES|HISTORY|NEWS|RELEASES?|NOTES)$/i.test(path)
+
+const TARGET = String.raw`["']?([^\s"';|&<>()]+)`
+const target = (part: string) =>
+  (new RegExp(String.raw`(?:^|[^\d<>&])>>?\s*` + TARGET).exec(part) ?? new RegExp(String.raw`\btee\s+(?:-a\s+)?` + TARGET).exec(part))?.[1]
+
+/**
+ * The file a shell command writes text to, and the text: a `cat` or `tee` heredoc whose own
+ * line redirects to a file, or an `echo`/`printf` whose own part of the command (between
+ * `&&`, `||`, `;` and new lines) sends it to a file with `>>`, `>` or `| tee`.
+ */
+export const shellWrite = (command: string): { file: string; text: string } | undefined => {
+  const clean = command.replace(/\d?>&\d|&>\s*\/dev\/null|\d?>\s*\/dev\/null/g, '')
+  const doc = /^[ \t]*(?:cat|tee)\b([^\n]*)<<-?\s*['"]?(\w+)['"]?([^\n]*)\n([\s\S]*?)\n\s*\2\s*$/m.exec(clean)
+  if (doc) {
+    const file = target(`${doc[1]} ${doc[3]}`) ?? (/^[ \t]*tee\b/m.test(doc[0]) ? target(doc[0].split('\n')[0]!) : undefined)
+    if (file && file !== '/dev/null') return { file, text: doc[4]! }
+  }
+  let file: string | undefined
+  const texts: string[] = []
+  for (const part of clean.replace(/<<-?\s*['"]?(\w+)['"]?[^\n]*\n[\s\S]*?\n\s*\1\s*$/gm, '').split(/&&|\|\||;|\n/)) {
+    if (!/^\s*(?:echo|printf)\b/.test(part)) continue
+    const to = target(part.replace(/\|\s*tee\b/, ' tee'))
+    if (!to || to === '/dev/null' || (file !== undefined && to !== file)) continue
+    file = to
+    const said = [...part.matchAll(/(?:"((?:[^"\\]|\\.)*)"|'([^']*)')/g)].map(m => (m[1] ?? m[2] ?? '').replace(/\\n/g, '\n'))
+    texts.push(said.length ? said.join('\n') : part)
+  }
+  return file === undefined ? undefined : { file, text: texts.join('\n') }
+}
+
+/** What a call changes in which file: the file's text before and after it. */
+async function change($: EngineInterface, x: Call): Promise<{ file: string; before: string; after: string }> {
+  const none = { file: '', before: '', after: '' }
+  if (x.tool === 'Write' && typeof x.content === 'string' && x.file_path) {
+    const before = (await $.fs.exists(x.file_path)) ? await $.fs.read(x.file_path) : ''
+    return { file: x.file_path, before, after: x.content }
+  }
+  if (x.tool === 'Edit' && typeof x.new_string === 'string' && typeof x.old_string === 'string' && x.file_path) {
+    const before = (await $.fs.exists(x.file_path)) ? await $.fs.read(x.file_path) : ''
+    // The whole file after the edit, so a date inside a sentence or a code block reads as one.
+    if (x.old_string && before.includes(x.old_string)) {
+      const after = x.replace_all ? before.split(x.old_string).join(x.new_string) : before.replace(x.old_string, () => x.new_string!)
+      return { file: x.file_path, before, after }
+    }
+    return { file: x.file_path, before: x.old_string, after: x.new_string }
+  }
+  if (x.tool === 'Bash' && typeof x.command === 'string') {
+    const w = shellWrite(x.command)
+    return w ? { file: w.file, before: '', after: w.text } : none
+  }
+  return none
+}
+
+const quote = (v: Verdict) => `"${v.stamp.text}" (in: ${v.stamp.line})`
+
+export const refusal = (vs: Verdict[]) =>
+  `date-check: ${vs.map(quote).join('; ')} ${vs.length === 1 ? 'is' : 'are'} in the future. ` +
+  `It is ${vs[0]!.real} now (local time). Write the real date and time, or leave the stamp out. ` +
+  `If a future date is meant (a deadline, a planned release), write the same text again and it goes through.`
+
+export const staleNote = (vs: Verdict[]) =>
+  `date-check: ${vs.map(quote).join('; ')} ${vs.length === 1 ? 'is' : 'are'} older than now (${vs[0]!.real}, local time). ` +
+  `If ${vs.length === 1 ? 'it records' : 'they record'} something past, leave ${vs.length === 1 ? 'it' : 'them'}; if ${vs.length === 1 ? 'it was' : 'they were'} meant as now, correct ${vs.length === 1 ? 'it' : 'them'}.`
+
+export const register: Register = (on, options: Options = {}) => {
+  const limits: Limits = {
+    aheadMinutes: num(options.aheadMinutes, LIMITS.aheadMinutes),
+    staleMinutes: num(options.staleMinutes, LIMITS.staleMinutes),
+    staleDays: num(options.staleDays, LIMITS.staleDays),
+  }
+  const notes = options.staleNotes !== false
+  // A future stamp refused once, by file and line: written again after that refusal, it is
+  // meant. Each refusal and each call's start take a number in order, so a call that began
+  // before the refusal (two calls at once) is refused too.
+  const meant = new Map<string, number>()
+  let order = 0
+
+  on('tool.call', async ($, e, next) => {
+    const x = e as unknown as Call
+    if (x.tool !== 'Write' && x.tool !== 'Edit' && x.tool !== 'Bash') return next(e)
+    const began = ++order
+    let verdicts: Verdict[] = []
+    let file = ''
+    try {
+      const now = await $.clock.now()
+      const w = await change($, x)
+      file = w.file
+      if (file && isText(file) && w.after) {
+        // Bare times in a file named for a later day are a plan for that day, not stamps.
+        const day = dateOfFile(file)
+        verdicts = judge(newStamps(w.before, w.after, day && day <= dayOf(now) ? day : undefined), now, limits)
+      }
+    } catch {
+      // A failure of this mod never stops the call.
+      verdicts = []
+    }
+    const key = (v: Verdict) => `${file}\n${v.stamp.line}`
+    const future = verdicts.filter(v => v.kind === 'future')
+    const fresh = future.filter(v => !((meant.get(key(v)) ?? Infinity) < began))
+    if (fresh.length) {
+      for (const v of fresh) meant.set(key(v), ++order)
+      return { deny: refusal(fresh) }
+    }
+    const done = await next(e)
+    if (done.deny !== undefined || done.isError) return done
+    const said = [
+      ...(future.length ? [`date-check: kept ${future.map(v => `"${v.stamp.text}"`).join(', ')} as written the second time (a date in the future on purpose).`] : []),
+      ...(notes && verdicts.some(v => v.kind === 'stale') ? [staleNote(verdicts.filter(v => v.kind === 'stale'))] : []),
+    ]
+    return said.length ? { ...done, context: [...(done.context ?? []), ...said] } : done
+  })
+}

package/hooks/stamps.ts

@@ -0,0 +1,173 @@
+// Finding the date and time stamps in text an agent is about to write, and judging each one
+// against the real clock. Pure: no file, no session; register.tsx feeds it text and the time.
+//
+// A stamp is a date or time in a place that says "this was written now": a heading that
+// carries a date (a changelog release, a dated log section), a labelled field (Date:,
+// Updated:, Released:, date: in frontmatter), or the opening of a line (a log line). A date
+// inside a sentence ("the outage on 2024-03-01") is an event, not a stamp, and is left alone.
+
+export type Stamp = {
+  /** The text as written, e.g. `2024-06-12` or `2026-10-31 16:05`. */
+  text: string
+  /** The line it was found on, trimmed, for the message. */
+  line: string
+  /** Where it was: a heading, a labelled field, a line's opening. */
+  where: 'heading' | 'field' | 'line-start'
+  /** Its date, `YYYY-MM-DD`. */
+  date: string
+  /** Minutes after midnight when it carries a time. */
+  minutes?: number
+  /** A UTC offset in minutes when it carries one (`Z` is 0). */
+  offset?: number
+}
+
+export type Verdict = { stamp: Stamp; kind: 'future' | 'stale'; real: string }
+
+const DATE = String.raw`(\d{4})-(\d{2})-(\d{2})`
+const TIME = String.raw`(?:[T ](\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?\s?(Z|[+-]\d{2}:?\d{2})?)?`
+const STAMP = DATE + TIME
+const LABEL = String.raw`(?:date|dated|updated|last[ _-]?updated|last[ _-]?modified|modified|released|release[ _-]?date|generated|written|created|as of|timestamp)`
+
+const heading = new RegExp(String.raw`^\s{0,3}#{1,6}\s.*?(?<![\d-])` + STAMP + String.raw`(?![\d-])`)
+const field = new RegExp(String.raw`^\s{0,3}(?:[-*+]\s+|>\s*|\|\s*)?[*_]*` + LABEL + String.raw`\**\s*[:=]\s*\**["'\x60]?(?:on\s)?` + STAMP + String.raw`(?![\d-])`, 'i')
+const opening = new RegExp(String.raw`^\s*(?:[-*+]\s+|>\s*)?[\[(]?` + STAMP + String.raw`(?![\d-])`)
+const timeOpening = /^\s*(?:[-*+]\s+|>\s*)?[\[(]?(\d{2}):(\d{2})(?::\d{2})?(?![\d:])[\])]?(?:\s|$|[,;|-])/
+
+const valid = (y: number, m: number, d: number) => {
+  if (m < 1 || m > 12 || d < 1) return false
+  return d <= new Date(Date.UTC(y, m, 0)).getUTCDate()
+}
+
+const offsetOf = (z: string | undefined) => {
+  if (z === undefined) return undefined
+  if (z === 'Z') return 0
+  const m = /^([+-])(\d{2}):?(\d{2})$/.exec(z)!
+  return (m[1] === '-' ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3]))
+}
+
+const build = (m: RegExpExecArray, at: number, line: string, where: Stamp['where']): Stamp | undefined => {
+  const [y, mo, d] = [Number(m[at]), Number(m[at + 1]), Number(m[at + 2])]
+  if (!valid(y, mo, d)) return undefined
+  const hh = m[at + 3], mm = m[at + 4]
+  const minutes = hh !== undefined ? Number(hh) * 60 + Number(mm) : undefined
+  if (minutes !== undefined && (Number(hh) > 23 || Number(mm) > 59)) return undefined
+  const date = `${m[at]}-${m[at + 1]}-${m[at + 2]}`
+  const text = m[0].slice(m[0].indexOf(date)).replace(/[\])"'\x60*]+$/, '').trim()
+  return { text, line: line.trim().slice(0, 120), where, date, ...(minutes !== undefined ? { minutes } : {}), ...(m[at + 5] !== undefined ? { offset: offsetOf(m[at + 5]) } : {}) }
+}
+
+/** A `YYYY-MM-DD` date in a file's name (logs/2026-10-31.md), the day its bare line times belong to. */
+export const dateOfFile = (path: string) => {
+  const m = /(?:^|[^\d])(\d{4})-(\d{2})-(\d{2})(?!\d)[^/\\]*$/.exec(path)
+  return m && valid(Number(m[1]), Number(m[2]), Number(m[3])) ? `${m[1]}-${m[2]}-${m[3]}` : undefined
+}
+
+/** A line inside an indented code block: four spaces or a tab, not a list item. */
+const indentedCode = (line: string) => /^(?: {4}|\t)/.test(line) && !/^\s*(?:[-*+]|\d+[.)])\s/.test(line)
+
+/** The stamp a line carries, if any. `fileDate` lets a bare `16:05` opening a line count as a stamp of that day. */
+const lineStamp = (line: string, fileDate?: string): Stamp | undefined => {
+  let m: RegExpExecArray | null
+  if ((m = heading.exec(line))) return build(m, 1, line, 'heading')
+  if ((m = field.exec(line))) return build(m, 1, line, 'field')
+  if ((m = opening.exec(line))) return build(m, 1, line, 'line-start')
+  if (fileDate && (m = timeOpening.exec(line)) && Number(m[1]) < 24 && Number(m[2]) < 60)
+    return { text: `${m[1]}:${m[2]}`, line: line.trim().slice(0, 120), where: 'line-start', date: fileDate, minutes: Number(m[1]) * 60 + Number(m[2]) }
+  return undefined
+}
+
+/**
+ * The stamps a change adds: the stamps on lines of `after` that `before` did not have, read
+ * in the whole of `after` (so a line inside a code block the file already had is seen as
+ * code). A stamp whose text was on a line the change removes is carried over, not added.
+ */
+export const newStamps = (before: string, after: string, fileDate?: string): Stamp[] => {
+  const had = new Map<string, number>()
+  for (const l of before.split(/\r?\n/)) had.set(l, (had.get(l) ?? 0) + 1)
+  const out: Stamp[] = []
+  let fence = false
+  for (const line of after.split(/\r?\n/)) {
+    const n = had.get(line) ?? 0
+    const isNew = n === 0
+    if (!isNew) had.set(line, n - 1)
+    if (/^\s*(```|~~~)/.test(line)) { fence = !fence; continue }
+    if (fence || !isNew || indentedCode(line)) continue
+    const s = lineStamp(line, fileDate)
+    if (s) out.push(s)
+  }
+  const removed = [...had.entries()].filter(([, n]) => n > 0).map(([l]) => l).join('\n')
+  return out.filter(s => !removed.includes(s.text))
+}
+
+/** The stamps in some lines of text. */
+export const stampsIn = (text: string, fileDate?: string): Stamp[] => newStamps('', text, fileDate)
+
+/** The lines of `after` that are not lines of `before`: what an edit adds. */
+export const addedLines = (before: string, after: string) => {
+  const had = new Map<string, number>()
+  for (const l of before.split(/\r?\n/)) had.set(l, (had.get(l) ?? 0) + 1)
+  const added: string[] = []
+  for (const l of after.split(/\r?\n/)) {
+    const n = had.get(l) ?? 0
+    if (n > 0) had.set(l, n - 1)
+    else added.push(l)
+  }
+  return added.join('\n')
+}
+
+const pad = (n: number) => String(n).padStart(2, '0')
+/** `YYYY-MM-DD` of a moment in local time, or at a fixed UTC offset in minutes. */
+export const dayOf = (ms: number, offset?: number) => {
+  const d = offset === undefined ? new Date(ms) : new Date(ms + offset * 60000)
+  return offset === undefined
+    ? `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+    : `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`
+}
+/** The local time now as a person writes it: `2026-10-31 16:42`. */
+export const nowText = (ms: number) => {
+  const d = new Date(ms)
+  return `${dayOf(ms)} ${pad(d.getHours())}:${pad(d.getMinutes())}`
+}
+
+/** The moment a stamp names, in ms: its zone when it carries one, the local zone when not. */
+const momentOf = (s: Stamp) => {
+  const [y, m, d] = s.date.split('-').map(Number) as [number, number, number]
+  const min = s.minutes ?? 0
+  if (s.offset !== undefined) return Date.UTC(y, m - 1, d, 0, min) - s.offset * 60000
+  return new Date(y, m - 1, d, 0, min).getTime()
+}
+
+export type Limits = { aheadMinutes: number; staleMinutes: number; staleDays: number }
+export const LIMITS: Limits = { aheadMinutes: 2, staleMinutes: 30, staleDays: 1 }
+
+/**
+ * Each stamp against the clock. A date alone is in the future when it is after today both
+ * locally and in UTC (a UTC date written in the evening west of Greenwich is not wrong); stale
+ * when more than `staleDays` before today. A time is in the future when more than
+ * `aheadMinutes` ahead of now; stale when more than `staleMinutes` behind it on the same day.
+ */
+export const judge = (stamps: Stamp[], now: number, limits: Limits = LIMITS): Verdict[] => {
+  const real = nowText(now)
+  const today = dayOf(now)
+  const todayUtc = dayOf(now, 0)
+  const out: Verdict[] = []
+  for (const s of stamps) {
+    if (s.minutes === undefined) {
+      const latest = today > todayUtc ? today : todayUtc
+      if (s.date > latest) out.push({ stamp: s, kind: 'future', real })
+      else {
+        const [y, m, d] = today.split('-').map(Number) as [number, number, number]
+        const oldest = dayOf(new Date(y, m - 1, d - limits.staleDays, 12).getTime())
+        if (s.date < oldest) out.push({ stamp: s, kind: 'stale', real })
+      }
+      continue
+    }
+    const at = momentOf(s)
+    if (at > now + limits.aheadMinutes * 60000) out.push({ stamp: s, kind: 'future', real })
+    else if (at < now - limits.staleMinutes * 60000) {
+      const days = s.offset === undefined ? s.date === today : dayOf(at) === today
+      if (days || (now - at) / 86400000 > limits.staleDays) out.push({ stamp: s, kind: 'stale', real })
+    }
+  }
+  return out
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@nightlab-agent/date-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Claude Code mod: checks the dates and times Claude Code writes into changelogs, logs, release notes and handoffs against the real clock before the write lands; a stamp in the future is refused with the real time.",
+  "keywords": [
+    "claude-code",
+    "claude-code-mod",
+    "claude-code-plugin",
+    "date",
+    "timestamp",
+    "changelog",
+    "hooks"
+  ],
+  "homepage": "https://github.com/nightlab-agent/date-check#readme",
+  "bugs": "https://github.com/nightlab-agent/date-check/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nightlab-agent/date-check"
+  },
+  "license": "MIT",
+  "author": "Nightlab",
+  "files": [
+    ".claude-plugin/",
+    "hooks/hooks.json",
+    "hooks/register.tsx",
+    "hooks/stamps.ts",
+    "CHANGELOG.md"
+  ]
+}