Report

Report: Writing the Session Report

The session states what it did, in a file, once, at the end.

Activation

Output Report: writing the session report..., then follow the rules below.

Context Guard

Triggers

The phrase always arms, on every install, with nothing configured. It is a phrase rather than a keyword because "report" appears in ordinary prose constantly.

Two environment variables add standing triggers on top of it. Both are unset by default, so a shipped install arms on the phrase and on nothing else.

Working directory: is separated out rather than left to the general list because it is the opening line of a dispatched task prompt, which is the shape this was built for, and because arming on it by default would file a report for a large share of every prompt anyone writes.

When either variable is configured, the SessionStart hook injects one sentence saying so. That sentence is the only announcement: a prompt carrying the phrase announces the requirement itself, so a default install is told nothing and pays nothing.

The 40 character floor

A prompt under 40 characters does not arm a prefix trigger. A standing prefix fires on "yes" and "commit" as readily as on a task, and a report about "commit" is noise filed under a real project name.

The floor applies to prefix triggers only. The phrase is exempt and arms at any length. A prompt consisting of nothing but Report per memstack:report is 26 characters and arms, because somebody typed the phrase on purpose and a short request is still a request. No one-word answer can contain the phrase, so the case the floor exists to stop is not a case the phrase can reach.

Re-arming

A later prompt that matches overwrites the marker, so each task prompt in a session owes its own report. The new marker carries a later request time than the file the previous prompt produced, so an earlier report cannot satisfy a later request.

Rules

1. Where it goes

MEMSTACK_REPORT_DIR when that variable is set and not empty, otherwise ~/.memstack/reports. Create the directory if it is absent.

A report is a session artifact, not a project file. Writing it into the working tree puts it in front of git status, and then in front of git add, and a report is not something anyone meant to commit.

2. What it is called

<project>-<YYYY-MM-DD>-<HHMMSS>.txt

• <project> is the leaf folder name of the working directory. Not the repo name, not the remote name: the folder, so two checkouts of one repo do not overwrite each other. When the prompt's first non-blank line names a working directory, that path's leaf is the project, not the directory the session was launched from. The gate reads the same line and keys the marker the same way, so a session opened in one repo and pointed at another agrees with itself.
• <YYYY-MM-DD> is today, local time.
• <HHMMSS> is the local wall clock time at the moment of writing: six digits, 24 hour, zero padded. Read the clock when the file is about to be written, not when the work started.

The suffix is a clock reading rather than a sequence number because a sequence has to be derived from what is already filed, and that derivation is what kept failing. Reports move into a subfolder once they are reviewed, the directory the count was taken from empties out, and the next report restarts at 01 on top of a name that is still in use one folder down. A clock has no state to lose.

3. How it is written

The Write tool only. Never a heredoc, never echo, never a shell redirection into a path.

On Windows the redirection operator is recognised before quote pairing is resolved, so one mis-paired quote anywhere in the command turns a redirect into a zero-byte file named after the fragment that followed it. This repository has collected four such files across three sessions, one of them from an arrow inside ordinary prose in a command that ran no code at all. The Write tool never touches a shell, so the hazard is not managed, it is absent.

4. What it may contain

• Plain ASCII. No em dashes, no smart quotes, no box drawing.
• No secret values. Not a key, not a token, not a password, not a signed URL, not the first six characters of any of them. A fingerprint (sha256, first 8 characters) or a length answers "is it set" and "are these the same" without emitting the value.

The no-secrets rule applies to the file exactly as it applies to the terminal, and the file is the more dangerous of the two: the terminal scrolls away, while the file sits on disk and gets read later, or pasted into a ticket.

5. How it ends

The last line states the session approximate context usage as shown on the status line, for example:

Context: approximately 62 percent of the window used at the time of writing.

A reader deciding whether to continue in this session or start a fresh one cannot see the status line the report was written from. One line tells them how much room is left.

6. What reaches the terminal

The file path, and one line saying what the report covers. Nothing else.

The body has already been written down. Printing it a second time doubles the cost of the session final turn and buries the path the reader actually needs.

7. Amending a report that is already written

A session may amend its own report after writing it, when it has something material to add. A measurement that finished later, a correction to something the report stated, or a finding that arrived after the write. It amends the file at the path it recorded, wherever that path now is. It never writes a second file.

The rule that a report is written once ends at the moment the session learns something the report should have said. Before this, a session in that position had nowhere to put it: writing again was forbidden and correctly refused, and amending was not permitted, so the information reached the terminal and stopped there.

The amendment is appended under its own heading. The body above it is left exactly as it was:

AMENDMENT 15:02:11 local
The background build finished after the report was written: 41 seconds,
which is the number the body says was still pending.

Appended rather than rewritten, because the reader may already have read the file. A rewritten body makes them read all of it again to find the sentence that changed; an appended section shows them what is new at a glance.

Never a second file. A second file is exactly the duplicate the gate was fixed to stop producing: the gate records the accepted report's path and answers later turns from that record, so an afterthought written to a fresh name leaves two reports for one request and leaves the reader to work out which one is current.

8. An amended report goes back to the top level

When the recorded path is inside a review subfolder of the report directory, move the amended file back to the top level once the amendment is written.

A file the reader has reviewed and filed away is unreviewed again the moment it changes. Filing is their signal that they are done with it, and they are not going to open it a second time, so an amendment left in the review folder is a change the reader never sees.

Move only the file this session wrote. Another session's report in the same folder is not this session's to move, however similarly it is named. The name is one report's identity; the shared prefix is every report this project filed today.

If a file of that name already sits at the top level, stop and report. Do not overwrite it, do not rename around it. The amendment is already safe in the file it was appended to, and two files carrying one name is a state somebody has to resolve by looking at both.

The terminal gets one line: the final path, and what the amendment added. Same reason as rule 6, and one more: the path may have changed, and a reader holding the old one needs to be told once rather than left to search.