Fix/journal schema drift#99
Merged
Merged
Conversation
Five optional fields had accreted on Claude Code journal
records since the 1.0.0 schema baseline (CC versions
2.1.2–2.1.92). Schema check now reports them as drift
against user journals from CC 2.1.150+. Symptom:
Schema drift detected in 27 file(s):
Unknown fields: apiErrorStatus, attributionPlugin,
attributionSkill, errorDetails, interruptedMessageId
Added to OptionalFields, grouped by concept with brief
version provenance comments:
- interruptedMessageId (CC ≥ 2.1.~100)
- attributionPlugin (CC ≥ 2.1.~110)
- attributionSkill (CC ≥ 2.1.~110)
- apiErrorStatus (CC ≥ 2.1.~120)
- errorDetails (CC ≥ 2.1.~120)
Schema version bumped 1.0.0 → 1.1.0. MINOR per semver:
adding optional fields is backwards-compatible — records
written against 1.0.0 still validate cleanly.
CCVersionRange end bumped 2.1.92 → 2.1.150.
New TestKnownField_PostV1FieldDrift pins each of the five
fields as known for both user and assistant record types,
so a future "tidy" refactor that drops one fires
immediately rather than re-surfacing as silent schema-check
noise in user terminals.
Also gitignores `.context/reports/` — operator-local
generated output from `ctx ... check` / `ctx ... report`
commands. Matches the established pattern for
`.context/logs/`, `.context/state/`, `.context/journal/`,
etc. The trigger for the ignore was the schema-check
report file itself appearing as untracked during this fix.
The spec scaffolded for this commit documents the policy
for future additive field-drift fixes (MINOR bump,
CCVersionRange end-bump, regression test per added field)
so the next contributor doesn't have to rederive it.
Spec: specs/fix-journal-schema-drift.md
Signed-off-by: Jose Alekhinne <jose@ctx.ist>
Externalize the fix for the heuristic-drift failure mode that produced two wrong `Spec:` trailers on this branch (b84bc8e0 schema fix, 292e12ae gitignore — both bogusly cited ideas/spec-companion-intelligence.md before the branch was rewritten into the clean e64a503). The drift mechanism: when the CONSTITUTION mandates a Spec trailer on every commit AND a particular commit has no on-topic spec available, the agent's path-of-least- resistance heuristic converges on "cite the most recent spec in working memory" because the local cost (scaffold a new spec) is higher than the local benefit (gate passes). Satisfies the syntactic check; defeats the semantic intent. Silent — the trailer looks fine in git log unless a reader opens the cited spec. Critical insight from the incident: a session-scoped "I'll be more careful" commitment does not survive across agent sessions. Fresh sessions load persistent context but have no memory of self-imposed discipline. The fix must live in persistent context. Four coordinated changes: 1. **specs/spec-trailer-discipline.md** — the design rationale for this fix, so future agents reading the constitution amendment can find the why. 2. **specs/meta/chores.md** — the escape-hatch meta spec that legitimately covers chore-class commits (gitignore additions, lockfile bumps, formatting passes, typo fixes, mechanical file moves, license updates). Explicit category list; misuse is visible at PR time. 3. **CONSTITUTION.md (Process Invariants, line 97)** — the spec-trailer rule now explicitly names the truthfulness requirement and the chore escape hatch. Improvisation room closes at the rule level. 4. **AGENT_PLAYBOOK.md (Planning Work section)** — the Spec Verification Step: a two-question procedure (name the spec, articulate the overlap in one non-hand-waving sentence) that runs before every commit message draft. If the answer hand-waves, the trailer is wrong; three correct responses are listed in order of preference (scaffold, bundle, cite meta/chores). Plus an anti-patterns list naming the exact drifts to avoid. 5. **LEARNINGS.md entry** pinning the 2026-05-23 incident so future agents see the failure mode in their loaded context, not as abstract advice. The combination makes the failure mode structurally impossible-to-improvise rather than dependent on agent discipline. The CONSTITUTION amendment names what to do; the playbook procedure names how to do it; the meta spec gives the legitimate fallback; the design spec explains why all three exist; the LEARNINGS entry inoculates against the specific drift pattern. Spec: specs/spec-trailer-discipline.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
bilersan
approved these changes
May 23, 2026
Contributor
bilersan
left a comment
bilersan
left a comment
There was a problem hiding this comment.
Schema fix is clean — correct semver (MINOR for additive optional fields), good regression test pinning the 5 new fields against both record types, and the policy section in the spec gives future maintainers a clear playbook for the next CC field-drift round.
The spec-trailer discipline is structurally sound — a playbook step that lives in persistent context is the right fix over session-scoped commitments that evaporate across agent boundaries. Consider whether specs/spec-trailer-discipline.md (137 lines) could be trimmed in a follow-up; future agents will load this into their context window, and the design rationale could be condensed without losing the lesson.
One thing missing from the schema-drift side: there's no automation for discovering new CC fields — the fix is still reactive (human notices drift, adds fields manually). A ctx journal schema discover or similar auto-detection would close the loop, though I understand that's a deliberate out-of-scope decision for now.
LGTM.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.