logging/overview.md and logging/api.md document contradictory hdb.log entry formats

[Ethan-Arrowood]

What's wrong

Two reference pages document the hdb.log entry format with different field orders, and both present it as "the standard format." One of them is wrong.

Page	Documented format
reference/logging/overview.md:26	<timestamp> [<thread>/<id>] [<level>] ...[<tags>]: <message>
reference/logging/api.md:128	<timestamp> [<level>] [<thread>/<id>]: <message>

overview.md puts thread before level; api.md puts level before thread. overview.md also documents a trailing [<tags>] field that api.md omits entirely, and its worked example at :32 follows its own ordering:

2023-03-09T14:25:05.269Z [main/0] [notify]: HarperDB successfully started.

api.md:134 additionally gives a distinct TaggedLogger form, <timestamp> [<level>] [<tag>]: <message>, with no thread field — which may be correct, may be a third variant, or may just be the same disagreement again.

Which one is right

Not determined. I traced the emitter as far as utility/logging/harper_logger.ts:778:

function logToFile(log) {
	let entry = `${new Date().toISOString()} ${log}${log.endsWith('\n') ? '' : '\n'}`;

That prepends only the ISO timestamp — every bracketed field is assembled by callers upstream, so the ordering is not visible at this layer. Settling it needs either a sample from a running instance or a trace of the call sites that build log. That is step one for whoever picks this up; please do not resolve it by picking the more plausible-looking page.

Also worth confirming while there: whether [<tags>] still exists as a field, and whether the TaggedLogger form genuinely drops the thread or whether that is the same error a third time.

Why this is worth fixing beyond the inconsistency

This is not only a reader-facing problem. Both files are declared whole-file sources for the logging rule in @harperfast/skills:

- path: reference/v5/logging/overview.md
  role: primary
- path: reference/v5/logging/api.md
  role: primary

The generator concatenates both and hands them to the model as one undifferentiated block with no per-source labels. Faced with two contradictory formats, it silently emitted only api.md's ordering and dropped overview.md's tags field, its worked example, and its field table (thread/id values main/http/job; tags values custom-function/auth-event). The generated rule's own "When to Use" advertises helping an agent "understand the log entry format."

Nothing flags this. validate-generated.mjs passes — it checks structure (manifest consistency, frontmatter, sourceCommit/inputHash, AGENTS.md round-trip, source-exists, byte-identical slices), not agreement between sources. So a contradiction in our docs is laundered into agent-facing rules with no signal, and whichever page the model happens to favor becomes the one agents act on.

The skills-side manifest cannot fix this. A generator can pick one of two contradictory inputs, but it cannot know which is true.

Suggested fix

1. Determine the actual emitted format (live sample or trace the callers of logToFile).
2. Correct whichever page is wrong, and reconcile the [<tags>] field and the TaggedLogger variant.
3. Prefer having one page own the format and the other link to it, rather than restating it. Two independent statements of the same format is what produced this.
4. Check the v4 versioned copies under reference_versioned_docs/version-v4/ against a v4 harper ref before touching them — do not assume v4 matches v5.

How this surfaced

Found during a coverage audit of docs-driven skill rule generation, which was itself prompted by a confirmed content loss in a different rule (HarperFast/skills#81). This one is a distinct failure mode: not material dropped for lack of an anchor, but two sources disagreeing and the disagreement being resolved silently.

_{sent with Claude Opus 5}