feat(framework): retention, version control status and schema versioning for the journal

[blafourcade]

Outcome

The run journal has a bounded size, a stated place in version control, and a reader that survives a schema change.

Scope

Three policies that must exist before data accumulates, because each is far more expensive to introduce afterwards.

• Version control status. .aidd/ is currently neither tracked nor gitignored in this repository, and aidd_docs/runs/ inherits that ambiguity. Decide, and state the consequence: a tracked journal puts who-worked-on-what-and-for-how-long into permanent history, which is the very thing feat(framework): measurement across tools and people #652 says cannot ship without an organisational decision.

• Retention and rotation. One file per session, forever, with no deletion path. A team of ten at twenty sessions a day reaches tens of thousands of files inside a year, in git, with no way to prune them that does not rewrite history.

• Schema versioning. Both runs/*.json and metadata.json carry schema_version: 1 and nothing says what a reader does with 2. feat(framework): an aidd-telemetry plugin whose hooks journal every session #620's strict nine-key whitelist makes every additive change a breaking one, which is the opposite of what a version field is for.

• Excludes: deletion of telemetry held in the sink, which belongs to the sink's own retention.

• Excludes: any hosted retention.

Done When

• aidd_docs/runs/ is either tracked or ignored by an explicit rule, never by omission.
• A rotation path exists that does not require rewriting history, and it is exercised in a test.
• A reader given schema_version: 2 behaves predictably and says so, rather than failing or silently misreading.
• An additive key does not break a reader written against the previous version, asserted with a fixture.
• aidd telemetry disable states what happens to data already written, and does what it states.

Completion Evidence

A journal grown past its retention bound, pruned, and still readable — plus a reader running against a fixture of the previous schema version.

Relations

Field	Value
parent	#631
related	#620, #646, #647

[blafourcade]

Out of the week's scope, 2026-08-16

Milestone 14 is scoped to what produces a trustworthy figure in five days: #620 the journal, #646 the switch, #647 the sink, #663 the step boundaries, #629 the figure, #617 the proof it is honest. Plus #658, which ships with them because the published documentation currently promises the opposite of what we are about to release.

This issue is not in that set. It keeps its value and its content; it simply is not what the week is measured on. It returns to the milestone board once the first figure exists.

No milestone is assigned rather than a later one, because where it lands depends on what the first week actually teaches.

[blafourcade]

One of the three questions is now answered, 2026-08-16

Version control status: decided. The journal is written outside the repository during a session and materialised into aidd_docs/runs/ on commit, and the placement is configurable. Recorded on #620.

That removes the ambiguity this issue opened with, and shrinks the retention problem at the same time: only records that accompany a commit ever enter history, so the growth rate is bounded by commits rather than by turns.

Two questions remain, and they are why this issue stays open.

• Retention and rotation. Bounded growth is not no growth. A pruning path that does not require rewriting history still has to exist, and it has to exist before there is anything to prune.
• Schema versioning. Both files carry schema_version: 1 and nothing says what a reader does with 2. feat(framework): an aidd-telemetry plugin whose hooks journal every session #620's strict key whitelist makes every additive change a breaking one, which is the opposite of what a version field is for.

There is also a third question now, raised by the configurability decision: which other properties should be configurable, and what the defaults are. Deliberately left open until the first figure exists and we know which knobs people reach for.

[blafourcade]

Two of the three are already delivered

Landed with the sink (#647) and the journal, so this ticket is smaller than it reads:

• Retention — day files older than 90 days are pruned, per file so one undeletable file does not spare every older one behind it. The window is measured rather than picked: a mapped request line is 576 bytes, so ~281 KB on a 500-request day and ~25 MB over the whole window.
• Schema versioning — both surfaces already carry one. The journal writes schema_version: 2 on its session_start line, once per file, so a reader can tell a file's shape without scanning it. The sink writes sink_schema_version: 1 on every line, and the reader throws UnknownTelemetrySinkSchemaVersionError on anything else rather than guessing.

What remains is the version-control question, which neither delivered: whether aidd_docs/runs/ should be committed, ignored, or partially ignored, and what happens to a journal file when the branch that produced it disappears. The repository's own .gitignore currently excludes aidd_docs/runs/* while tracking marker files - asserted by test - but that is this repository's choice, not a decision the framework makes for a user's project.

[blafourcade]

Two of the five boxes are closed by #776 (5788ad88). Three were already met before this ticket was picked up — checked against the tree rather than taken from the description, which had gone stale in one place.

Closed by #776

• A reader given schema_version: 2 behaves predictably and says so. The hook stamps schema_version on every session_start (record.cjs's SCHEMA_VERSION), and the reader dropped it: parseSessionStart never looked at the field. A journal written under a schema whose line shapes had changed was read as if it were this one. The reader now carries the stated schema and refuses one it does not read, and aidd telemetry check gains journal-in-another-schema so the refusal is reported as a version disagreement rather than falling through to "the recorder is declared nowhere" or "none carry a readable session_start" — both false about a file whose header parsed perfectly well.
• An additive key does not break a reader, asserted with a fixture. A key the reader has never heard of, under a schema it knows, costs it neither the header nor the boundaries.

Already met

• aidd_docs/runs/ is either tracked or ignored by an explicit rule, never by omission. The scope says ".aidd/ is currently neither tracked nor gitignored in this repository". That is no longer true: .gitignore carries .aidd/* with !.aidd/config.json, and aidd_docs/runs/* with !aidd_docs/runs/.gitkeep and !aidd_docs/runs/README.md. git ls-files aidd_docs/runs returns those two files and nothing else.
• A rotation path exists that does not require rewriting history, and it is exercised in a test. aidd telemetry forget removes run files by the name listRunFiles() gave them, through deleteRunFile, confined by isBareFileName, with e2e coverage. Nothing being tracked, no history is rewritten.
• aidd telemetry disable states what happens to data already written. The command is telemetry off; it states what stays and warns when a tool's own settings file still exports, and forget is the verb that removes.

Worth a rewrite of the scope's first bullet before this closes, so the next reader is not sent to check a fact that changed.