werkregie/doc/prs/2026-10-14-PR#85-journal-summary.md

PR#85: An AI Summary as the Description of a Werkjournal Entry

Version: minor

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

Related Links

• werkregie PR#84: JournalProposer at a Mutation-CRAP of at most 15, the prerequisite.

Problem

The description of a proposed Werkjournal entry is built by rules: the story, the pull requests, the tasks, the sessions and the Matrix rooms, joined by semicolons. It names what happened, but reads as a list, not as a description of the work.

Werkjournal adds a changed entry as a new one, so the same data must give the same text.

Non-Goals

• No transcripts as input; the model gets the evidence of the entry only, as the rules do.
• No change of the rule text.

Specification

Feature: an AI summary as the description of a Werkjournal entry

Scenario#85.01: the switch takes the AI summary into the entries and the file

… so that the human imports a readable description.

• Given a day with an entry of the project Werkregie and a configured journal.summary
• When the human selects "KI" in the tab Journal
• Then the entry shows the AI summary of its evidence, and the copied or downloaded file holds it

Verified by

• JournalProposerTest "each entry of the file gets the AI summary of its evidence; the file keeps the rule text"
• journal.test.js "the rules take the rule text, the AI its summary"
• EntrySummariesTest "the chat model gets the instructions and the evidence with the key, and its text is the summary"
• manual check in the browser, see "Solution"

Scenario#85.02: the same data gives the same summary

… so that a second import adds no entry to Werkjournal.

• Given a day whose proposal was summarized once
• When the human opens the proposal of that day again, also after a restart of the server
• Then each entry shows the same summary, and the model is not asked again

Verified by

• EntrySummariesTest "the same input gives the same summary, after a restart too, and the model is asked once"
• EntrySummariesTest "a summary in use is kept beyond the time since it was written"
• EntrySummariesTest "the model gets the project, the story and the evidence of the entry, in the order of the proposal"

Scenario#85.03: without a model the rules stay

… so that a configuration without a model works as before.

• Given no journal.summary in the configuration
• When the human opens the tab Journal
• Then the tab shows no switch, and each entry the rule text

Verified by

• EntrySummariesTest "no model configured is no summaries; a missing key is their problem; a key from the environment works"
• journal.test.js "an entry without summary keeps the rule text under the AI too"

Scenario#85.04: a failing model leaves the rule text and names the cause

… so that the human can import the day all the same.

• Given a configured journal.summary whose model fails
• When the human selects "KI"
• Then each entry keeps the rule text, and the tab names the cause

Verified by

• JournalProposerTest "a failing model leaves the entries without summary and names the cause"
• EntrySummariesTest "without a model, or with an empty answer, there is no summary and the cause is named"
• manual check in the browser, see "Solution"

Scenario#85.05: the choice stays

… so that the human does not select it for each day.

• Given the tab Journal with "KI" selected
• When the human picks another day or opens the page again
• Then "KI" stays selected

Verified by

• manual check in the browser, see "Solution"

Solution

• journal.summary configures the chat model, as claude.summary does; without it, nothing changes.
• EntrySummaries asks the model for each entry of the file, in parallel, with the project, the story and the evidence; the instructions ask for one or two German sentences of at most 300 characters, without invented facts. It keeps each summary by the SHA-256 of its input in <stateDir>/journal-summaries.json, 400 days after its last use; one lock per input keeps two requests of the same day from two answers.
• ProposedEntry.summary carries the summary; Proposal.summaryError the first failure, e.g. a missing key. The file of the server keeps the rule text; the page builds the imported file from the text the switch picks.
• The tab Journal shows the switch "Regeln | KI" when an entry has a summary or the proposal an error; the page keeps the choice, and a correction of the human stays with the text it corrected.
• journalDescription and journalField move into static/journal.js, tested by jsTest (ADR 0002).

Manual Check

On 2026-10-14, a local dashboard with the recorded day 2026-10-13 and journal.summary with Haiku through OpenRouter:

• The first proposal took 6 s and gave, e.g. for the project Werk: "Werkjournal-Import pro Kalendertag, Kunden-, Projekt- und Gewohnheitsangaben aus importierten Einträgen (PR#6), …"; the second took 0.03 s and gave the same texts from journal-summaries.json.
• "KI" showed the summaries in the entries, "Regeln" the rule texts; the choice stayed after a reload.
• Without the key, the switch stayed, the entries kept the rule text, and the tab said "Keine KI-Zusammenfassung: kein Schlüssel in OPENROUTER_API_KEY".

Release Notes

The tab Journal offers an AI summary of each entry beside the rule text, with the switch "Regeln | KI"; the server needs journal.summary for it.

Additional Changes

• dashboard.server.example.yml names journal.summary.

Open Questions

None.