What this is
None of these are defects — the code works. They are places where CONTRACTS/ and AGENTS.md describe a codebase that has moved. Filed together because they are one workstream: bring the contract back level with the code.
1. Two service files are missing from the layering map
CONTRACTS/START_HERE.md §3 lists cron.sh, database.sh, editor.sh, focus-function.sh, help.sh. On disk there are also:
A reader trusting the map does not know they exist.
2. CONV-PORTABLE says date(1) lives only in core/time.sh — seven sites call it
lib/export.sh:12 date +%Y%m%d_%H%M%S
lib/import.sh:39 date +%Y%m%d_%H%M%S
focus-checkin:36 date +%Y-%m-%d
services/cron.sh:104 date +%M
services/cron.sh:139 date +%M
services/cron.sh:147 date +%H
services/cron.sh:148 date +%M
All are plain date +FMT, which is POSIX and behaves identically on GNU and BSD — nothing is broken. The rule as written is simply stricter than the code.
The check that enforces it cannot see them. AGENTS.md §5:
grep -rn '^[^#]*\(date --date\|date -d \|date +%s\|date -Iseconds\)' ...
# Expected: no output
That pattern matches only the four non-portable forms, so date +%M passes silently and the drift check reports clean. Either the rule should be narrowed to "no GNU/BSD-divergent date invocations outside core/time.sh" — which is what the grep actually tests, and what matters — or the call sites should move.
3. CMD-REPORT does not mention markdown
CONTRACTS/MAIN.md:543-548 describes only which queries the command uses. Since #39 the command emits a markdown document on stdout — a period line, a project table, one section per session, notes verbatim.
4. CMD-OFF does not mention the duplicate fold
CMD-OFF still reads:
prompt for notes (Enter to skip), record_session, then end_session; notify.
Since #36, off may instead offer to append into an existing same-named session — which skips record_session entirely — or cancel the stop and leave the clock running. CMD-PAST has the same gap for past add / past modify.
5. CMD-CHECKIN does not mention the desktop guard
Nothing in MAIN.md mentions XDG_RUNTIME_DIR, has_desktop_display, or the rule that the check-in refuses to launch a dialog with no session to draw on. That guard is the whole of #35, and without it in the contract a future change could remove it as dead weight — the failure it prevents is a SIGABRT coredump, which does not look like a failure the caller can detect.
Why it's needed
START_HERE.md says the contract is the authority and the tests are the verifier. Where the two disagree the contract wins, so drift makes it possible to "fix" working code back into a bug — item 5 is the clearest example. Item 2 additionally means one of the automated drift checks currently reports clean on a rule it cannot test.
What this is
None of these are defects — the code works. They are places where
CONTRACTS/andAGENTS.mddescribe a codebase that has moved. Filed together because they are one workstream: bring the contract back level with the code.1. Two service files are missing from the layering map
CONTRACTS/START_HERE.md §3listscron.sh,database.sh,editor.sh,focus-function.sh,help.sh. On disk there are also:services/merge.sh— the duplicate-session fold (Focus on allowed duplicate entries #36)services/desktop.sh— the desktop-session guard (kdialog errors when querying for checkin #35)A reader trusting the map does not know they exist.
2.
CONV-PORTABLEsaysdate(1)lives only incore/time.sh— seven sites call itAll are plain
date +FMT, which is POSIX and behaves identically on GNU and BSD — nothing is broken. The rule as written is simply stricter than the code.The check that enforces it cannot see them.
AGENTS.md §5:That pattern matches only the four non-portable forms, so
date +%Mpasses silently and the drift check reports clean. Either the rule should be narrowed to "no GNU/BSD-divergentdateinvocations outsidecore/time.sh" — which is what the grep actually tests, and what matters — or the call sites should move.3.
CMD-REPORTdoes not mention markdownCONTRACTS/MAIN.md:543-548describes only which queries the command uses. Since #39 the command emits a markdown document on stdout — a period line, a project table, one section per session, notes verbatim.4.
CMD-OFFdoes not mention the duplicate foldCMD-OFFstill reads:Since #36,
offmay instead offer to append into an existing same-named session — which skipsrecord_sessionentirely — or cancel the stop and leave the clock running.CMD-PASThas the same gap forpast add/past modify.5.
CMD-CHECKINdoes not mention the desktop guardNothing in
MAIN.mdmentionsXDG_RUNTIME_DIR,has_desktop_display, or the rule that the check-in refuses to launch a dialog with no session to draw on. That guard is the whole of #35, and without it in the contract a future change could remove it as dead weight — the failure it prevents is a SIGABRT coredump, which does not look like a failure the caller can detect.Why it's needed
START_HERE.mdsays the contract is the authority and the tests are the verifier. Where the two disagree the contract wins, so drift makes it possible to "fix" working code back into a bug — item 5 is the clearest example. Item 2 additionally means one of the automated drift checks currently reports clean on a rule it cannot test.