The message engine outlives its substrate — harvested to Kanban/Changes/ as the change narrator

Step 2 of strategy/01-git-excision.md: CommitMessageEngine and the composer seam relocate to a neutral module renamed away from commit vocabulary (ChangeNarrator, ChangeNarrationRequest, ChangeNarrating, SemanticChangeNarration, ChangeAuthorship), GitChangedPath extracts from GitCommitOperation as ChangedPath, and the one git tie severs — authorship's foreign case carries a display name, not a GitIdentity. The spec tests transplant as ChangeNarratorTests, alive until the journal work begins. 3,009 tests green.

Claude-Session: https://claude.ai/code/session_014PtZdPwqZuqEDLc6wZMtEy

Kanban/Changes/ChangeNarration.swift

@@ -0,0 +1,157 @@
+import Foundation
+
+/// Harvested 2026-08-08 from `Kanban/Git/` per `strategy/01-git-excision.md`, with its git ties
+/// severed — this is the designated core of the future activity feed / foreign-change journal. The
+/// "previous snapshot" a narration request carries is supplied by the caller by contract: the git
+/// stack supplied it from HEAD, and the journal will supply it from memory/snapshots.
+
+// MARK: - Authorship
+
+/// Which of the three classes a commit is — the axis the message engine is allowed to know about.
+///
+/// The composer receives it because 06-history-undo.md ▸ Commit messages gives one rule that turns
+/// on it (the root commit's fixed subject) and one that deliberately does not: "**Foreign commits
+/// speak the same vocabulary.** Origin lives in the author field (structural attribution), not in
+/// message prose — a foreign move reads 'Move card …' exactly like an app-mediated one". The
+/// composer card therefore gets the fact and is expected to ignore it for phrasing; having it means
+/// it never has to be plumbed later, and having it *named* means the rule about not using it has
+/// something to point at.
+public enum ChangeAuthorship: Sendable, Equatable {
+    /// The user acting through the app.
+    case user
+    /// A scheduled heal's own commit (ruled 2026-07-29).
+    case heal
+    /// Everything else, carrying the display name it will be recorded under.
+    case foreign(String)
+}
+
+// MARK: - The request
+
+/// Everything the message engine is handed for one commit.
+///
+/// **A struct rather than an argument list**, because the point of this seam is that the semantic
+/// composer plugs into it without reshaping the engine: any input it turns out to need joins this
+/// type rather than every call site. It did need two — `previousSnapshot` and `agentGuideText`, both
+/// below — and that is exactly what this shape was for.
+///
+/// **Everything here is a value, and that is the design.** The composer (`ChangeNarrator`) reads
+/// no file and opens no repository: the flush resolves the environment once — the board as HEAD has
+/// it, the board as the app has it, the guide's bytes — and the message is then a pure function of
+/// this struct. Resolving once per *flush* rather than once per planned commit also means a
+/// three-way-split window materializes HEAD's tree once, not three times.
+public struct ChangeNarrationRequest: Sendable {
+
+    /// The board this is a commit in.
+    public let boardRoot: URL
+
+    /// **The changed-path list** (06 ▸ Commit messages ▸ Non-snapshot files commit too: "beside the
+    /// snapshot diff it receives the changed-path list, and non-snapshot paths compose *path-shaped
+    /// events*"), narrowed to the paths *this* commit stages.
+    public let changedPaths: [ChangedPath]
+
+    /// Which class this commit is.
+    public let authorship: ChangeAuthorship
+
+    /// Whether this is the repository's first commit — the one commit with a subject of its own
+    /// ("Initial board state", 06 ▸ Rules ▸ Abnormal repo states).
+    public let isRootCommit: Bool
+
+    /// **The current half** of the composer's "last-committed vs. current" diff — the board as the
+    /// app last read it, or, where no store is attached, as the flush read it off disk itself.
+    ///
+    /// `nil` only when neither could answer: a board whose working tree does not load at all, which
+    /// is a commit that will have to be described by its paths.
+    public let snapshot: BoardModel?
+
+    /// **The last-committed half** of the "last-committed vs. current" diff — supplied by the caller
+    /// by contract; the narrator itself never reads this from anywhere. The git stack supplied it from
+    /// HEAD's tree (`GitHeadSnapshot`), the former git-backed supplier; the journal will supply it from
+    /// memory/snapshots.
+    ///
+    /// `nil` when the caller has nothing to diff against — the git stack's case was an unborn HEAD
+    /// (where `isRootCommit` already says everything) or a HEAD whose tree did not load as a board. The
+    /// git stack read it from the repository rather than carrying it forward from the last commit the
+    /// app made, because the app is not the only writer and because launch catch-up has no carried
+    /// value to offer: see `GitHeadSnapshot` for the whole of that argument.
+    public let previousSnapshot: BoardModel?
+
+    /// **The board-root `CLAUDE.md` as it now reads**, when this commit touches it — the one
+    /// non-snapshot file with a subject of its own ("Update agent guide (vN)", 06 ▸ Commit messages).
+    ///
+    /// The *text*, not the version: N is "a pure function of file content"
+    /// (`AgentGuide.installedVersion`), and keeping the parse on the composer's side is what keeps
+    /// that rule where the message vocabulary is. `nil` when the guide is not in this commit, cannot
+    /// be read, or has been deleted.
+    public let agentGuideText: String?
+
+    /// **When each of this commit's comments was created** — keyed by the comment folder's
+    /// board-root-relative path, as `ChangeNarrator.commentFolder(of:)` spells it.
+    ///
+    /// The second value on this struct that a *file* has to be read for, and it is here for
+    /// `agentGuideText`'s reason exactly: "a commit's comment bullets sort chronologically — by the
+    /// comments' own `created`, folder name on ties" (06 ▸ Rules ▸ Auto-commit, blessed 2026-07-31),
+    /// and `created` lives in a comment's own `index.md` because comments are window-scoped and the
+    /// board snapshot never carries them (01-storage-format.md § Enhanced schema). The flush resolves
+    /// it once (`GitAutoCommitter.commentTimestamps(for:boardRoot:)`) and the engine stays a pure
+    /// function of values.
+    ///
+    /// **Missing is normal, not a defect.** A comment whose folder left the tree in this very commit
+    /// (the close purge), one whose `index.md` does not parse, one written by hand with no `created`
+    /// at all — each is simply absent here and sorts after its dated siblings in folder-name order,
+    /// which is `CommentThread.sorted`'s own fallback for the same field.
+    public let commentTimestamps: [String: Date]
+
+    public init(
+        boardRoot: URL,
+        changedPaths: [ChangedPath],
+        authorship: ChangeAuthorship,
+        isRootCommit: Bool,
+        snapshot: BoardModel?,
+        previousSnapshot: BoardModel? = nil,
+        agentGuideText: String? = nil,
+        commentTimestamps: [String: Date] = [:]
+    ) {
+        self.boardRoot = boardRoot
+        self.changedPaths = changedPaths
+        self.authorship = authorship
+        self.isRootCommit = isRootCommit
+        self.snapshot = snapshot
+        self.previousSnapshot = previousSnapshot
+        self.agentGuideText = agentGuideText
+        self.commentTimestamps = commentTimestamps
+    }
+}
+
+// MARK: - The seam
+
+/// **What a commit says** (06-history-undo.md ▸ Commit messages).
+///
+/// The implementation is `SemanticChangeNarration` below, over `ChangeNarrator`: "a pure, testable
+/// function" composing from a structural diff of two board snapshots, with the whole
+/// Add/Delete/Move/Rename/Edit vocabulary, plural folding, path-shaped events for non-snapshot files,
+/// and the trash pair. The protocol survives its interim purpose because it is still what lets a test
+/// inject a fake and assert *when* a message was asked for without asserting what it said.
+///
+/// `Sendable` because composition runs off the main actor, inside the same detached task that stages
+/// and commits — the message has to be in hand before `git_commit_create` is called, and none of the
+/// work is main-actor work.
+public protocol ChangeNarrating: Sendable {
+    func narrative(for request: ChangeNarrationRequest) -> String
+}
+
+// MARK: - The wired composer
+
+/// **The semantic composer**, and the committer's default (`GitAutoCommitter.composer`).
+///
+/// A one-line conformance over `ChangeNarrator`, deliberately: the vocabulary is worth a file of
+/// its own and nothing about it should have to know that a protocol exists. The type stays because
+/// the seam takes an existential, and because a *named* default is what makes "the engine's composer
+/// is the semantic one" assertable.
+public struct SemanticChangeNarration: ChangeNarrating {
+
+    public init() {}
+
+    public func narrative(for request: ChangeNarrationRequest) -> String {
+        ChangeNarrator.narrative(for: request)
+    }
+}