wingfoil 0.2.1

package/dist/memory/audit.d.ts

@@ -0,0 +1,177 @@
+/** One commit's attribution, as audited against `pathspecs` (REQ-SEC-02's "0 unknown author"). */
+export interface AttributionEntry {
+    readonly sha: string;
+    readonly authorName: string;
+    readonly authorEmail: string;
+    /** ISO-8601 author date (`git log --format=%aI`) — sourced from git, never file content. */
+    readonly date: string;
+    readonly subject: string;
+    /** Whether this commit's author identity is non-empty and not a git-guessed placeholder. */
+    readonly valid: boolean;
+}
+/**
+ * Whether `name`/`email` look like a real, deliberately-configured git identity rather than an
+ * empty or git-guessed placeholder, as recorded on a *historical* commit. The base check — non-empty
+ * `name` AND non-empty `email` — is NOT re-derived here: it delegates to
+ * {@link isConfiguredIdentity} from `src/core/git-identity.ts`, the single source of truth also used
+ * by `requireGitIdentity`'s write-time precondition (REQ-SEC-01). On top of that shared base, this
+ * audit (REQ-SEC-02) layers two read-only augmentations that only make sense when inspecting
+ * *historical* commits rather than live config — `requireGitIdentity` has no need for either, because
+ * it only ever looks at the identity a caller is about to write with:
+ *
+ *  - Rejects the `GIT_GUESSED_DOMAIN_MARKER` (`.(none)`): git appends this to an author email when it
+ *    fell back to a guessed identity at commit time. `requireGitIdentity` now PREVENTS this going
+ *    forward (task-014), but older history predating that guard can still carry it, so the read audit
+ *    must flag it — it is a legacy-history concern, not part of the live write-time rule.
+ *  - Rejects a non-empty-but-malformed email (`EMAIL_RE`): `requireGitIdentity` never needs this check
+ *    because it only reads a git config value (itself always syntactically well-formed or absent);
+ *    historical commit authors, however, can carry hand-edited or otherwise malformed values, so the
+ *    audit validates the shape too.
+ *
+ * Pure predicate — no filesystem/git access.
+ */
+export declare function isValidAttribution(name: string, email: string): boolean;
+/**
+ * Walk every commit touching any of `pathspecs` under `root`, oldest first, annotated with whether
+ * its author attribution is valid ({@link isValidAttribution}) — the audit primitive behind
+ * REQ-SEC-02's "0 'unknown author'" fit criterion. `pathspecs` is sorted before being passed to git
+ * so the invocation itself is deterministic regardless of caller-supplied order (REQ-SYS-07); a
+ * commit touching more than one of the given pathspecs still appears exactly once (git's own log
+ * de-duplicates by commit, not by path). Returns `[]` (never throws) when none of `pathspecs` has
+ * any history, mirroring {@link getMemoryHistory}.
+ */
+export declare function auditAttribution(root: string, pathspecs: readonly string[]): AttributionEntry[];
+/** Parsed `Approver:`/`Reason:` lines from an `approve`/`reject` commit body (CLAUDE.md §5.1). */
+export interface ApprovalMetadata {
+    readonly approverName: string;
+    readonly approverEmail: string;
+    readonly approverRole: string;
+    /**
+     * The `Reason:` block this commit records, or `null` when it records none that can be read
+     * (`dl-067-reason-trailer-contract` clause 6). Widened from `string` by
+     * `task-072-fix-reason-trailer-contract`: an unreadable reason must not take a successfully parsed
+     * approver identity down with it, and `MemoryTransition.reason` was already `string | null`.
+     */
+    readonly reason: string | null;
+}
+/**
+ * The `Reason:` a commit body records, on its own — `null` when the body has none (a plain
+ * `add`/`submit` body, which carries no trailer by convention), or carries a bare `Reason:` with no
+ * value. Split out of {@link parseApprovalMetadata} by `task-049-memory-history` (P1.10) because the
+ * two trailers do not always travel together: an APPROVAL-gate commit (`approve`/`reject`) must carry
+ * both `Approver:` and `Reason:` (CLAUDE.md §5.1, P1.7), but a `deprecate` commit records a `Reason:`
+ * with **no** `Approver:` line at all — deprecate is explicitly not an approval gate. Reading the
+ * reason through `parseApprovalMetadata` would therefore drop every deprecate reason from the audit
+ * trail it exists to surface.
+ *
+ * The reason's extent is NOT decided here: this is a thin alias over `parseReasonBlock`
+ * (`./commit-message.ts`), the module that also writes the trailer — one grammar, consumed by both
+ * sides, which is `dl-067-reason-trailer-contract` clause 5 and the property that module's doc has
+ * claimed for itself since `task-045-memory-submit`.
+ *
+ * The limitation this function used to document — "a hypothetical multi-paragraph reason would be
+ * silently truncated to its first line here" — is gone with the defect
+ * (`bug-042-reason-text-has-no-contract-against-commit-trailer`, F1). It was never hypothetical: 79 of
+ * `main`'s 171 approve/reject commits carry a reason continuing past line one, and the reader kept as
+ * little as 2% of one (dl-067 E1/E2).
+ */
+export declare function parseCommitReason(body: string): string | null;
+/**
+ * Parse a commit body for the `Approver: Name <email> (role)` and `Reason: ...` trailers
+ * (CLAUDE.md §5.1; REQ-SEC-02/REQ-SEC-04). Returns `null` when there is no `Approver:` trailer line —
+ * e.g. for a plain `add`/`submit` body, or a `deprecate` one (not an approval gate), neither of which
+ * records an approval at all. A caller that wants such a commit's reason wants
+ * {@link parseCommitReason} instead.
+ *
+ * All-or-nothing on the APPROVER, and only on the approver (`dl-067` clause 6,
+ * `task-072-fix-reason-trailer-contract`). It used to be all-or-nothing in both directions, so an
+ * unreadable `Reason:` discarded the identity this function had already parsed successfully — and
+ * since an empty `--reason` was accepted at exit `0` and git's cleanup turned it into a bare
+ * `Reason:`, `wingfoil memory history` could report an approval gate crossed by nobody, for no reason
+ * (bug-042 F2). Now the record degrades instead of vanishing: the approver stands, `reason` reads
+ * `null`. Nothing on `main` reads differently for it — no commit there has a bare `Reason:` or is
+ * missing a trailer line (dl-067 E6) — so this is protection for bodies written before the fix.
+ */
+export declare function parseApprovalMetadata(body: string): ApprovalMetadata | null;
+/** The CLAUDE.md §5.1 verb a commit's subject declares, when it matches the `wf({type}): {verb} ...` shape. */
+type MemoryOperation = 'add' | 'submit' | 'approve' | 'reject' | 'deprecate';
+/**
+ * One reconstructed transition in a Memory element's history — author/timestamp from git itself,
+ * `fromState`/`toState` derived from the document's own frontmatter `status:` field at that commit
+ * (ADR-007: state lives in frontmatter, not the commit message), and `approval` parsed from the
+ * commit body when present. `fromState` is `null` only for the element's first commit (creation —
+ * there is no prior state to name).
+ */
+export interface MemoryTransition {
+    readonly sha: string;
+    readonly authorName: string;
+    readonly authorEmail: string;
+    readonly date: string;
+    readonly subject: string;
+    readonly operation: MemoryOperation | null;
+    readonly fromState: string | null;
+    readonly toState: string | null;
+    readonly approval: ApprovalMetadata | null;
+    /**
+     * The `Reason:` this commit's body records, read INDEPENDENTLY of `Approver:`
+     * ({@link parseCommitReason}) — `null` when the body records none. Deliberately not the same field
+     * as `approval.reason`: `approval` is `null` for a `deprecate` commit (it has no `Approver:` line),
+     * yet such a commit does record a reason, and `wingfoil memory history` (P1.10) must surface it.
+     * When `approval` is non-null the two always agree, by construction.
+     */
+    readonly reason: string | null;
+}
+/**
+ * Reconstruct every transition `relativePath` went through, oldest first, entirely from git log
+ * (`getMemoryHistory`) plus a frontmatter read at each commit (`git show`) — no separate log file
+ * (ADR-007). This is the derivation `wingfoil memory history` (P1.10) renders — `src/core`'s
+ * `memoryHistory` operation (`task-049-memory-history`) renames and string-formats these fields into
+ * its own entry shape, deriving no further state of its own; this function is the reconstruction
+ * itself, not that command's output formatting.
+ *
+ * **Renames are followed on both halves of the derivation**, which is the correction
+ * `task-097-memory-history-reads-each-commit-at-its-historical-path` made. `getMemoryHistory` always
+ * walked with `git log --follow`, so it *found* the commits preceding a rename; `readStatusAt` then
+ * read each of them at the CURRENT path, which those trees do not contain, so all of them reported
+ * `null` states (`bug-080-…`). The walk now carries the path each commit actually used
+ * (`MemoryHistoryEntry.path`, from `--follow --name-status`) and this function reads at that path —
+ * the walk is the source of truth for "where was this file at this commit", and the read no longer
+ * guesses.
+ *
+ * This was never the hypothetical the TSDoc here used to call "a documented edge case, not a live
+ * defect": `docs/self/docs/04_memory/planning/v1/*` became `planning/rl-v1/*` in a single commit,
+ * moving five `release` elements at once, precisely BECAUSE the `release` type's `path` pattern
+ * interpolates a component — the release-line id — that itself changed. Any edit to a `path`
+ * pattern, or to an id one interpolates, renames documents.
+ *
+ * `toState` is still `null` where a commit in the walk genuinely has no document to read — before
+ * the element's creation, or after a deletion. That is a legitimate answer, distinct from the defect
+ * above, and it no longer arrives with a `fatal:` on the operator's stderr (`bug-071`; see
+ * {@link readStatusAt}).
+ */
+export declare function reconstructMemoryTransitions(root: string, relativePath: string): MemoryTransition[];
+/** One disagreement between the commit subject's `[old → new]` bracket and the frontmatter actually committed. */
+export interface ConsistencyMismatch {
+    readonly sha: string;
+    readonly subject: string;
+    readonly declared: {
+        readonly from: string;
+        readonly to: string;
+    };
+    readonly derived: {
+        readonly from: string | null;
+        readonly to: string | null;
+    };
+}
+/**
+ * Cross-check, for every transition that carries a `[old → new]` bracket in its subject (`approve`/
+ * `reject`/`deprecate`, per CLAUDE.md §5.1 — a plain `add`/`submit` subject has no bracket and is
+ * skipped), that the bracket's declared states agree with the states independently derived from the
+ * document's own frontmatter at that commit ({@link reconstructMemoryTransitions}). Returns `[]` when
+ * every bracketed transition agrees — REQ-SEC-02/REQ-STATE-02's "no drift between the two views";
+ * any entry in the returned array is a genuine inconsistency (e.g. a hand-edited commit message that
+ * doesn't match what was actually written to disk).
+ */
+export declare function verifyTransitionConsistency(root: string, relativePath: string): ConsistencyMismatch[];
+export {};
+//# sourceMappingURL=audit.d.ts.map

package/dist/memory/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/memory/audit.ts"],"names":[],"mappings":"AA2CA,kGAAkG;AAClG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAQD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAMvE;AAID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAY/F;AAID,kGAAkG;AAClG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAUD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAO3E;AAID,+GAA+G;AAC/G,KAAK,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAI7E;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AA8CD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAuBnG;AAID,kHAAkH;AAClH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAChF;AAMD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAuBrG"}

package/dist/memory/audit.js

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidAttribution = isValidAttribution;
+exports.auditAttribution = auditAttribution;
+exports.parseCommitReason = parseCommitReason;
+exports.parseApprovalMetadata = parseApprovalMetadata;
+exports.reconstructMemoryTransitions = reconstructMemoryTransitions;
+exports.verifyTransitionConsistency = verifyTransitionConsistency;
+/**
+ * Audit-trail verification & reconstruction (task-015-complete-audit-trail, REQ-SEC-02) — the
+ * READ/verify half of "every state change is a git commit with author + timestamp" (ADR-001,
+ * ADR-007): git history is the *only* audit trail (no secondary `.wingfoil/state/` log), so this
+ * module audits and reconstructs that trail directly from `git log`/`git show`, never from a value
+ * written into file content. It builds on task-011's {@link getMemoryHistory} (the raw commit walk)
+ * rather than re-implementing it.
+ *
+ * This module deliberately does **not** enforce attribution at write time (checking that a commit
+ * *can* be made) — that precondition belongs to task-014-git-identity-required (REQ-SEC-01,
+ * `requireGitIdentity` in `src/core/git-identity.ts`). This module only ever reads commits that
+ * already exist and reports on them; nothing here blocks or gates a write. The base "non-empty
+ * name and non-empty email" rule the two share lives in exactly one place — the
+ * `isConfiguredIdentity` predicate exported by `src/core/git-identity.ts` — which
+ * {@link isValidAttribution} below consumes rather than re-deriving; see that function's
+ * doc-comment for the read-only augmentations it layers on top for historical commits.
+ *
+ * REQ-SEC-02's fit criterion, mapped to the functions below:
+ *
+ * - "`git log` verification ... shows author + timestamp for every change with 0 'unknown
+ *   author'" -> {@link auditAttribution} / {@link isValidAttribution}.
+ * - Commit timestamp (never file content) supplies the ISO-8601 date -> already true of
+ *   `getMemoryHistory`'s `date` field (`%aI`, sourced from git itself); this module never re-derives
+ *   a timestamp from anywhere else.
+ * - "`approve`/`reject` commits carry an explicit `Approver:`/`Reason:` line" ->
+ *   {@link parseApprovalMetadata}.
+ * - "`memory history <id>` lists each transition ... author, timestamp, and reason" ->
+ *   {@link reconstructMemoryTransitions}.
+ * - "Recomputing an element's state at any historical commit ... agrees with the transition history
+ *   derived from git log ... no drift" -> {@link verifyTransitionConsistency}.
+ */
+const child_process_1 = require("child_process");
+const core_1 = require("../core");
+const validation_1 = require("../validation");
+const commit_message_1 = require("./commit-message");
+const history_1 = require("./history");
+const git_log_1 = require("./git-log");
+const storage_1 = require("../storage");
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@()]+$/;
+// The literal marker git itself appends to an author email when it falls back to a guessed identity
+// (user@hostname) and cannot determine a real domain — e.g. "root@buildhost.(none)". A commit
+// carrying this is not a deliberately-configured identity, so it counts as "unknown author".
+const GIT_GUESSED_DOMAIN_MARKER = '.(none)';
+/**
+ * Whether `name`/`email` look like a real, deliberately-configured git identity rather than an
+ * empty or git-guessed placeholder, as recorded on a *historical* commit. The base check — non-empty
+ * `name` AND non-empty `email` — is NOT re-derived here: it delegates to
+ * {@link isConfiguredIdentity} from `src/core/git-identity.ts`, the single source of truth also used
+ * by `requireGitIdentity`'s write-time precondition (REQ-SEC-01). On top of that shared base, this
+ * audit (REQ-SEC-02) layers two read-only augmentations that only make sense when inspecting
+ * *historical* commits rather than live config — `requireGitIdentity` has no need for either, because
+ * it only ever looks at the identity a caller is about to write with:
+ *
+ *  - Rejects the `GIT_GUESSED_DOMAIN_MARKER` (`.(none)`): git appends this to an author email when it
+ *    fell back to a guessed identity at commit time. `requireGitIdentity` now PREVENTS this going
+ *    forward (task-014), but older history predating that guard can still carry it, so the read audit
+ *    must flag it — it is a legacy-history concern, not part of the live write-time rule.
+ *  - Rejects a non-empty-but-malformed email (`EMAIL_RE`): `requireGitIdentity` never needs this check
+ *    because it only reads a git config value (itself always syntactically well-formed or absent);
+ *    historical commit authors, however, can carry hand-edited or otherwise malformed values, so the
+ *    audit validates the shape too.
+ *
+ * Pure predicate — no filesystem/git access.
+ */
+function isValidAttribution(name, email) {
+    const trimmedName = name.trim();
+    const trimmedEmail = email.trim();
+    if (!(0, core_1.isConfiguredIdentity)(trimmedName, trimmedEmail))
+        return false;
+    if (trimmedEmail.includes(GIT_GUESSED_DOMAIN_MARKER))
+        return false;
+    return EMAIL_RE.test(trimmedEmail);
+}
+const AUDIT_LOG_FIELDS = ['%H', '%an', '%ae', '%aI', '%s'];
+/**
+ * Walk every commit touching any of `pathspecs` under `root`, oldest first, annotated with whether
+ * its author attribution is valid ({@link isValidAttribution}) — the audit primitive behind
+ * REQ-SEC-02's "0 'unknown author'" fit criterion. `pathspecs` is sorted before being passed to git
+ * so the invocation itself is deterministic regardless of caller-supplied order (REQ-SYS-07); a
+ * commit touching more than one of the given pathspecs still appears exactly once (git's own log
+ * de-duplicates by commit, not by path). Returns `[]` (never throws) when none of `pathspecs` has
+ * any history, mirroring {@link getMemoryHistory}.
+ */
+function auditAttribution(root, pathspecs) {
+    const sortedPathspecs = [...pathspecs].sort();
+    const records = (0, git_log_1.walkGitLogFields)(root, AUDIT_LOG_FIELDS, sortedPathspecs);
+    return records.map(([sha = '', authorName = '', authorEmail = '', date = '', subject = '']) => ({
+        sha,
+        authorName,
+        authorEmail,
+        date,
+        subject,
+        valid: isValidAttribution(authorName, authorEmail),
+    }));
+}
+/**
+ * The identity on an `Approver:` trailer line. Applied to that ONE line — located by
+ * {@link parseApproverTrailerLine}, which anchors it to the body's first — rather than searched for
+ * anywhere in the body with `/m`, so a second `Approver:` line sitting inside some reason's text can
+ * never be read as an approval record (`dl-067` clause 5; bug-042 F3).
+ */
+const APPROVER_LINE_RE = /^Approver:\s*(.+?)\s*<([^>]+)>\s*\(([^)]+)\)\s*$/;
+/**
+ * The `Reason:` a commit body records, on its own — `null` when the body has none (a plain
+ * `add`/`submit` body, which carries no trailer by convention), or carries a bare `Reason:` with no
+ * value. Split out of {@link parseApprovalMetadata} by `task-049-memory-history` (P1.10) because the
+ * two trailers do not always travel together: an APPROVAL-gate commit (`approve`/`reject`) must carry
+ * both `Approver:` and `Reason:` (CLAUDE.md §5.1, P1.7), but a `deprecate` commit records a `Reason:`
+ * with **no** `Approver:` line at all — deprecate is explicitly not an approval gate. Reading the
+ * reason through `parseApprovalMetadata` would therefore drop every deprecate reason from the audit
+ * trail it exists to surface.
+ *
+ * The reason's extent is NOT decided here: this is a thin alias over `parseReasonBlock`
+ * (`./commit-message.ts`), the module that also writes the trailer — one grammar, consumed by both
+ * sides, which is `dl-067-reason-trailer-contract` clause 5 and the property that module's doc has
+ * claimed for itself since `task-045-memory-submit`.
+ *
+ * The limitation this function used to document — "a hypothetical multi-paragraph reason would be
+ * silently truncated to its first line here" — is gone with the defect
+ * (`bug-042-reason-text-has-no-contract-against-commit-trailer`, F1). It was never hypothetical: 79 of
+ * `main`'s 171 approve/reject commits carry a reason continuing past line one, and the reader kept as
+ * little as 2% of one (dl-067 E1/E2).
+ */
+function parseCommitReason(body) {
+    return (0, commit_message_1.parseReasonBlock)(body);
+}
+/**
+ * Parse a commit body for the `Approver: Name <email> (role)` and `Reason: ...` trailers
+ * (CLAUDE.md §5.1; REQ-SEC-02/REQ-SEC-04). Returns `null` when there is no `Approver:` trailer line —
+ * e.g. for a plain `add`/`submit` body, or a `deprecate` one (not an approval gate), neither of which
+ * records an approval at all. A caller that wants such a commit's reason wants
+ * {@link parseCommitReason} instead.
+ *
+ * All-or-nothing on the APPROVER, and only on the approver (`dl-067` clause 6,
+ * `task-072-fix-reason-trailer-contract`). It used to be all-or-nothing in both directions, so an
+ * unreadable `Reason:` discarded the identity this function had already parsed successfully — and
+ * since an empty `--reason` was accepted at exit `0` and git's cleanup turned it into a bare
+ * `Reason:`, `wingfoil memory history` could report an approval gate crossed by nobody, for no reason
+ * (bug-042 F2). Now the record degrades instead of vanishing: the approver stands, `reason` reads
+ * `null`. Nothing on `main` reads differently for it — no commit there has a bare `Reason:` or is
+ * missing a trailer line (dl-067 E6) — so this is protection for bodies written before the fix.
+ */
+function parseApprovalMetadata(body) {
+    const approverLine = (0, commit_message_1.parseApproverTrailerLine)(body);
+    const approverMatch = approverLine === null ? null : APPROVER_LINE_RE.exec(approverLine);
+    if (!approverMatch)
+        return null;
+    const [, approverName = '', approverEmail = '', approverRole = ''] = approverMatch;
+    return { approverName, approverEmail, approverRole, reason: parseCommitReason(body) };
+}
+const OPERATION_RE = /^wf\([^)]+\):\s*(add|submit|approve|reject|deprecate)\b/;
+/**
+ * Read `historicalPath`'s frontmatter `status:` field as it existed at `sha` (`git show sha:path`),
+ * without validating it against any type's Zod schema — this is a historical-snapshot read, not a
+ * live document validation. Returns `null` if the path didn't exist at `sha`, has no frontmatter
+ * block, or the frontmatter has no string `status` field.
+ *
+ * `historicalPath` is the path the element occupied **at that commit** — `MemoryHistoryEntry.path`,
+ * produced by the same `--follow` walk that selected the commit — never the caller's current path.
+ * Passing the current one was `bug-080-read-status-at-reads-the-current-path-at-pre-rename-commits`:
+ * every commit older than a rename asked git for a path that tree does not contain, the read failed,
+ * and the transition reported `null` states. `dl-080` — a read that gates an operation resolves at
+ * `HEAD` — does not reach here: this read gates nothing, and its subject is by construction *other*
+ * commits.
+ *
+ * The explicit `stdio` is `bug-071-read-status-at-leaks-git-stderr`, and it is not made redundant by
+ * the paragraph above. `execFileSync` hands the child this process's own stderr by default, so on
+ * the failure that remains legitimate — a commit where the document genuinely does not exist, before
+ * its creation or after a deletion — git's `fatal: path ... does not exist in '<sha>'` went straight
+ * to the operator's terminal while the command reported success. Capturing it into a pipe this
+ * process owns (and discarding it, the failure being handled right here) is what keeps a genuine
+ * `fatal:` distinguishable from a routine one — that line is how `bug-050`'s forged history
+ * announced itself.
+ */
+function readStatusAt(root, sha, historicalPath) {
+    let raw;
+    try {
+        raw = (0, child_process_1.execFileSync)('git', ['-C', root, 'show', `${sha}:${historicalPath}`], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        return null;
+    }
+    const { frontmatter } = (0, storage_1.splitFrontmatter)(raw);
+    if (!frontmatter)
+        return null;
+    const parsed = (0, validation_1.parseYaml)(frontmatter, `${historicalPath}@${sha}`);
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const status = parsed.status;
+    return typeof status === 'string' ? status : null;
+}
+/**
+ * Reconstruct every transition `relativePath` went through, oldest first, entirely from git log
+ * (`getMemoryHistory`) plus a frontmatter read at each commit (`git show`) — no separate log file
+ * (ADR-007). This is the derivation `wingfoil memory history` (P1.10) renders — `src/core`'s
+ * `memoryHistory` operation (`task-049-memory-history`) renames and string-formats these fields into
+ * its own entry shape, deriving no further state of its own; this function is the reconstruction
+ * itself, not that command's output formatting.
+ *
+ * **Renames are followed on both halves of the derivation**, which is the correction
+ * `task-097-memory-history-reads-each-commit-at-its-historical-path` made. `getMemoryHistory` always
+ * walked with `git log --follow`, so it *found* the commits preceding a rename; `readStatusAt` then
+ * read each of them at the CURRENT path, which those trees do not contain, so all of them reported
+ * `null` states (`bug-080-…`). The walk now carries the path each commit actually used
+ * (`MemoryHistoryEntry.path`, from `--follow --name-status`) and this function reads at that path —
+ * the walk is the source of truth for "where was this file at this commit", and the read no longer
+ * guesses.
+ *
+ * This was never the hypothetical the TSDoc here used to call "a documented edge case, not a live
+ * defect": `docs/self/docs/04_memory/planning/v1/*` became `planning/rl-v1/*` in a single commit,
+ * moving five `release` elements at once, precisely BECAUSE the `release` type's `path` pattern
+ * interpolates a component — the release-line id — that itself changed. Any edit to a `path`
+ * pattern, or to an id one interpolates, renames documents.
+ *
+ * `toState` is still `null` where a commit in the walk genuinely has no document to read — before
+ * the element's creation, or after a deletion. That is a legitimate answer, distinct from the defect
+ * above, and it no longer arrives with a `fatal:` on the operator's stderr (`bug-071`; see
+ * {@link readStatusAt}).
+ */
+function reconstructMemoryTransitions(root, relativePath) {
+    const history = (0, history_1.getMemoryHistory)(root, relativePath); // oldest first already
+    const transitions = [];
+    let previousState = null;
+    for (const entry of history) {
+        const toState = readStatusAt(root, entry.sha, entry.path);
+        const operationMatch = OPERATION_RE.exec(entry.subject);
+        transitions.push({
+            sha: entry.sha,
+            authorName: entry.authorName,
+            authorEmail: entry.authorEmail,
+            date: entry.date,
+            subject: entry.subject,
+            operation: operationMatch?.[1] ?? null,
+            fromState: previousState,
+            toState,
+            approval: parseApprovalMetadata(entry.body),
+            reason: parseCommitReason(entry.body),
+        });
+        previousState = toState;
+    }
+    return transitions;
+}
+// Matches the `[old-state → new-state]` bracket CLAUDE.md §5.1 mandates on approve/reject/deprecate
+// subjects (the arrow is the U+2192 character used throughout CLAUDE.md/the memory templates).
+const BRACKET_RE = /\[([^[\]→]+?)\s*→\s*([^[\]]+?)\]\s*$/;
+/**
+ * Cross-check, for every transition that carries a `[old → new]` bracket in its subject (`approve`/
+ * `reject`/`deprecate`, per CLAUDE.md §5.1 — a plain `add`/`submit` subject has no bracket and is
+ * skipped), that the bracket's declared states agree with the states independently derived from the
+ * document's own frontmatter at that commit ({@link reconstructMemoryTransitions}). Returns `[]` when
+ * every bracketed transition agrees — REQ-SEC-02/REQ-STATE-02's "no drift between the two views";
+ * any entry in the returned array is a genuine inconsistency (e.g. a hand-edited commit message that
+ * doesn't match what was actually written to disk).
+ */
+function verifyTransitionConsistency(root, relativePath) {
+    const transitions = reconstructMemoryTransitions(root, relativePath);
+    const mismatches = [];
+    for (const transition of transitions) {
+        const match = BRACKET_RE.exec(transition.subject);
+        if (!match)
+            continue;
+        const [, declaredFromRaw = '', declaredToRaw = ''] = match;
+        const declaredFrom = declaredFromRaw.trim();
+        const declaredTo = declaredToRaw.trim();
+        if (declaredFrom !== transition.fromState || declaredTo !== transition.toState) {
+            mismatches.push({
+                sha: transition.sha,
+                subject: transition.subject,
+                declared: { from: declaredFrom, to: declaredTo },
+                derived: { from: transition.fromState, to: transition.toState },
+            });
+        }
+    }
+    return mismatches;
+}
+//# sourceMappingURL=audit.js.map

package/dist/memory/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/memory/audit.ts"],"names":[],"mappings":";;AAkFA,gDAMC;AAaD,4CAYC;AA+CD,8CAEC;AAkBD,sDAOC;AA4GD,oEAuBC;AAyBD,kEAuBC;AA9WD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,iDAA6C;AAE7C,kCAA+C;AAC/C,8CAA0C;AAE1C,qDAA8E;AAC9E,uCAA6C;AAC7C,uCAA6C;AAC7C,wCAA8C;AAgB9C,MAAM,QAAQ,GAAG,8BAA8B,CAAC;AAChD,oGAAoG;AACpG,8FAA8F;AAC9F,6FAA6F;AAC7F,MAAM,yBAAyB,GAAG,SAAS,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,kBAAkB,CAAC,IAAY,EAAE,KAAa;IAC5D,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAChC,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAClC,IAAI,CAAC,IAAA,2BAAoB,EAAC,WAAW,EAAE,YAAY,CAAC;QAAE,OAAO,KAAK,CAAC;IACnE,IAAI,YAAY,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QAAE,OAAO,KAAK,CAAC;IACnE,OAAO,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;AAE3D;;;;;;;;GAQG;AACH,SAAgB,gBAAgB,CAAC,IAAY,EAAE,SAA4B;IACzE,MAAM,eAAe,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAA,0BAAgB,EAAC,IAAI,EAAE,gBAAgB,EAAE,eAAe,CAAC,CAAC;IAE1E,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,EAAE,EAAE,UAAU,GAAG,EAAE,EAAE,WAAW,GAAG,EAAE,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9F,GAAG;QACH,UAAU;QACV,WAAW;QACX,IAAI;QACJ,OAAO;QACP,KAAK,EAAE,kBAAkB,CAAC,UAAU,EAAE,WAAW,CAAC;KACnD,CAAC,CAAC,CAAC;AACN,CAAC;AAkBD;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,kDAAkD,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,iBAAiB,CAAC,IAAY;IAC5C,OAAO,IAAA,iCAAgB,EAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,qBAAqB,CAAC,IAAY;IAChD,MAAM,YAAY,GAAG,IAAA,yCAAwB,EAAC,IAAI,CAAC,CAAC;IACpD,MAAM,aAAa,GAAG,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzF,IAAI,CAAC,aAAa;QAAE,OAAO,IAAI,CAAC;IAEhC,MAAM,CAAC,EAAE,YAAY,GAAG,EAAE,EAAE,aAAa,GAAG,EAAE,EAAE,YAAY,GAAG,EAAE,CAAC,GAAG,aAAa,CAAC;IACnF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;AACxF,CAAC;AAOD,MAAM,YAAY,GAAG,yDAAyD,CAAC;AA6B/E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,GAAW,EAAE,cAAsB;IACrE,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,IAAA,4BAAY,EAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,cAAc,EAAE,CAAC,EAAE;YAC1E,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,EAAE,WAAW,EAAE,GAAG,IAAA,0BAAgB,EAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAE9B,MAAM,MAAM,GAAG,IAAA,sBAAS,EAAC,WAAW,EAAE,GAAG,cAAc,IAAI,GAAG,EAAE,CAAC,CAAC;IAClE,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE/D,MAAM,MAAM,GAAI,MAAkC,CAAC,MAAM,CAAC;IAC1D,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,4BAA4B,CAAC,IAAY,EAAE,YAAoB;IAC7E,MAAM,OAAO,GAAG,IAAA,0BAAgB,EAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,uBAAuB;IAE7E,MAAM,WAAW,GAAuB,EAAE,CAAC;IAC3C,IAAI,aAAa,GAAkB,IAAI,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1D,MAAM,cAAc,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACxD,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,SAAS,EAAG,cAAc,EAAE,CAAC,CAAC,CAAiC,IAAI,IAAI;YACvE,SAAS,EAAE,aAAa;YACxB,OAAO;YACP,QAAQ,EAAE,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC;YAC3C,MAAM,EAAE,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC;SACtC,CAAC,CAAC;QACH,aAAa,GAAG,OAAO,CAAC;IAC1B,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAYD,oGAAoG;AACpG,+FAA+F;AAC/F,MAAM,UAAU,GAAG,sCAAsC,CAAC;AAE1D;;;;;;;;GAQG;AACH,SAAgB,2BAA2B,CAAC,IAAY,EAAE,YAAoB;IAC5E,MAAM,WAAW,GAAG,4BAA4B,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACrE,MAAM,UAAU,GAA0B,EAAE,CAAC;IAE7C,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK;YAAE,SAAS;QAErB,MAAM,CAAC,EAAE,eAAe,GAAG,EAAE,EAAE,aAAa,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC;QAC3D,MAAM,YAAY,GAAG,eAAe,CAAC,IAAI,EAAE,CAAC;QAC5C,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC;QAExC,IAAI,YAAY,KAAK,UAAU,CAAC,SAAS,IAAI,UAAU,KAAK,UAAU,CAAC,OAAO,EAAE,CAAC;YAC/E,UAAU,CAAC,IAAI,CAAC;gBACd,GAAG,EAAE,UAAU,CAAC,GAAG;gBACnB,OAAO,EAAE,UAAU,CAAC,OAAO;gBAC3B,QAAQ,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,UAAU,EAAE;gBAChD,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,SAAS,EAAE,EAAE,EAAE,UAAU,CAAC,OAAO,EAAE;aAChE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/memory/commit-message.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The one commit-message formatter for Memory state-transition verbs (task-045-memory-submit).
+ *
+ * Every verb — `submit` today, `approve`/`reject`/`deprecate` next — produces exactly one commit whose
+ * subject is `wf({type}): {verb} {id1}, {id2}` (`spec-004-mcp-surface-contract` §4.3), optionally
+ * followed by a ` [from → to]` bracket and an `Approver:` / `Reason:` body for the verbs whose
+ * evidence rules require them (P1.7/P1.8, REQ-SEC-04). Those are exactly the shapes
+ * `./audit.ts` reads back for `wingfoil memory history` (P1.10): `OPERATION_RE` on the subject,
+ * `BRACKET_RE` on the bracket, `parseApprovalMetadata`/`parseCommitReason` on the body. Building the
+ * message in one place is what keeps writer and reader from drifting apart.
+ *
+ * Since `task-072-fix-reason-trailer-contract` this module also owns the **reason grammar** —
+ * {@link normalizeReason}, {@link reasonDefect}, {@link parseReasonBlock} and
+ * {@link parseApproverTrailerLine} — ratified by `dl-067-reason-trailer-contract` and fixing
+ * `bug-042-reason-text-has-no-contract-against-commit-trailer`. `--reason <text>` is arbitrary free
+ * text and the trailer is line-oriented; before dl-067 no rule said what happened when the two met, so
+ * a blank reason was recorded as a bare `Reason:` that destroyed the whole approval record, a
+ * multi-line one was truncated to its first line on read, and one shaped like a trailer could forge a
+ * second `Approver:` line. Putting the grammar HERE, next to the formatter, and having `./audit.ts`
+ * consume it is what makes this module doc's "one place" claim true rather than aspirational: the
+ * writer cannot emit a reason the reader cannot recover.
+ *
+ * Pure and deterministic (REQ-SYS-07): the output is a function of the input alone; ids keep the order
+ * the caller gives.
+ */
+import type { TransitionOp } from './state-machine';
+/** Why a `--reason` value cannot be recorded in the trailer, per `dl-067` clause 4 and its corollary. */
+export type ReasonDefect = 
+/** Empty, or nothing but whitespace: git would store a bare `Reason:` and both parsers would fail. */
+'blank'
+/** Carries a line starting `Approver:` or `Reason:` — a forged trailer line (bug-042 F3). */
+ | 'reserved-trailer-line'
+/**
+ * Ends in a paragraph made entirely of trailer-shaped lines, which {@link parseReasonBlock} would
+ * read as git's own trailer block and drop. The corollary of the block's termination rule: without
+ * it, the round-trip equality dl-067 clause 3 promises would be false for this one input shape. 0 of
+ * `main`'s 172 reason blocks end this way, so the refusal costs the existing corpus nothing.
+ */
+ | 'trailing-trailer-paragraph';
+/**
+ * The refusal message for `defect` — the single source of the wording the CLI prints and
+ * `spec-008-cli-grammar` §2 pins. Deliberately distinct from `missing required argument: --reason`
+ * (`src/core/require-reason.ts`), which answers the *omitted* case that spec-008 §2 and the P1.7/P1.8
+ * BDD features already quote verbatim (dl-067 S1).
+ */
+export declare function reasonDefectMessage(defect: ReasonDefect): string;
+/**
+ * The declared normal form of a reason (`dl-067` clause 3) — two rules, from two different sources,
+ * and it is worth keeping them apart:
+ *
+ *  1. **git's**, which applies whether or not this function exists. `commitPaths`
+ *     (`src/storage/commit.ts`) commits with `-m`, so git's `cleanup=whitespace` strips per-line
+ *     trailing whitespace, collapses runs of blank lines to one, and drops leading and trailing blank
+ *     lines. This is why `spec-008-cli-grammar` §2's original "Recorded verbatim" was already false
+ *     for any multi-line text, independently of bug-042.
+ *  2. **This module's**: the first line's leading whitespace is trimmed. git does NOT do this. It is
+ *     needed because that line sits after `Reason: ` on the same physical line and
+ *     {@link parseReasonBlock} consumes the key together with the whitespace that follows it — so
+ *     without the trim, a reason beginning with spaces would not round-trip equally.
+ *
+ * Applying both HERE, on the way in, is what turns "approximately what you typed" into an assertable
+ * equality: what {@link parseReasonBlock} reads back out of the commit is exactly this function's
+ * output. Interior indentation is preserved by both rules — it carries meaning in real approval prose.
+ *
+ * Idempotent, and a pure function of its input (REQ-SYS-07).
+ */
+export declare function normalizeReason(reason: string): string;
+/**
+ * Why `reason` cannot be recorded in the `Reason:` trailer, or `null` when it can (`dl-067` clause 4).
+ *
+ * Judged on the NORMALIZED text ({@link normalizeReason}), because that is what would actually be
+ * stored — otherwise a defect could hide behind trailing whitespace git strips on the way in. This is
+ * the ONE place the rule is decided: `src/core/require-reason.ts` turns a non-`null` result into the
+ * `UsageError` (exit 2) the CLI boundary reports, and {@link formatMemoryCommitMessage} refuses the
+ * same values so no caller can route around that boundary.
+ */
+export declare function reasonDefect(reason: string): ReasonDefect | null;
+/**
+ * The `Reason:` a commit body records, read as a BLOCK (`dl-067` clause 2): the remainder of the
+ * `Reason:` line plus every following body line, up to (exclusive) git's trailing trailer paragraph or
+ * the end of the body. `null` when the body records no reason, or records a bare `Reason:` with no
+ * value — the shape git's cleanup leaves behind when an empty reason is written (bug-042 F2), which
+ * `parseApprovalMetadata` degrades around rather than treating as an absent approval.
+ *
+ * This replaces the first-line capture `/^Reason:\s*(.+)$/m` that preceded it, and that is a real
+ * change to how existing history reads: 79 of `main`'s 171 approve/reject commits (46%) carry a reason
+ * continuing past line one, and every one of them was silently halved. It is a recovery, not a
+ * reinterpretation — the text was always in the commit; only the reader dropped it.
+ *
+ * A generic `Key: value` line INSIDE the block is ordinary prose and does not end it; only a trailing
+ * paragraph made entirely of trailer lines does (dl-067 E5).
+ */
+export declare function parseReasonBlock(body: string): string | null;
+/**
+ * The commit body's `Approver:` trailer line, or `null` when it has none — anchored to the body's
+ * FIRST non-empty line (`dl-067` clause 5). {@link formatMemoryCommitMessage} has always emitted it
+ * there, and it is the first body line in 171 of `main`'s 171 approve/reject commits (dl-067 E4), so
+ * anchoring costs no existing commit its approver while closing bug-042 F3 on the read side: an
+ * `Approver:` line appearing anywhere else is text some reason happens to contain, never an approval
+ * record. `./audit.ts` destructures the returned line into an identity — that shape is its concern;
+ * the line's POSITION is this module's.
+ */
+export declare function parseApproverTrailerLine(body: string): string | null;
+/** The identity recorded on an approval-gate commit's `Approver:` line. */
+export interface CommitApprover {
+    readonly name: string;
+    readonly email: string;
+    readonly role: string;
+}
+/** Everything one Memory transition commit message is built from. */
+export interface MemoryCommitMessageInput {
+    /** The Memory element type all `ids` belong to — one commit is scoped to one type. */
+    readonly type: string;
+    /** The verb, which is also the subject's operation word. `add` is included for completeness. */
+    readonly op: TransitionOp | 'add';
+    /** The element ids moved by this commit, in the order they are listed in the subject. */
+    readonly ids: readonly string[];
+    /** When given, appended to the subject as ` [from → to]`. Omitted for `add`/`submit` (spec-004 §4.3). */
+    readonly transition?: {
+        readonly from: string;
+        readonly to: string;
+    };
+    /** When given, an `Approver: Name <email> (role)` body line. */
+    readonly approver?: CommitApprover;
+    /**
+     * When given, a `Reason:` block ({@link parseReasonBlock}) — written in the declared normal form
+     * ({@link normalizeReason}), and refused outright when {@link reasonDefect} says it could not be
+     * read back.
+     */
+    readonly reason?: string;
+}
+/**
+ * Format a Memory transition commit message: the subject, then — only when an approver or reason is
+ * given — a blank line and the `Approver:` / `Reason:` lines in that order.
+ *
+ * The reason is emitted in its declared normal form and, when it carries a defect
+ * ({@link reasonDefect}), refused rather than written. The CLI boundary
+ * (`src/core/require-reason.ts`) already refuses the same values with the same messages at exit 2, so
+ * reaching this throw means a caller bypassed that boundary — it exists so no *future* caller can
+ * (dl-067 clause 5; bug-042 F2/F3).
+ *
+ * @throws `Error` when `ids` is empty: a transition commit always names what it moved.
+ * @throws `Error` when `reason` cannot be recorded in the trailer, carrying that defect's message.
+ */
+export declare function formatMemoryCommitMessage(input: MemoryCommitMessageInput): string;
+//# sourceMappingURL=commit-message.d.ts.map

package/dist/memory/commit-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-message.d.ts","sourceRoot":"","sources":["../../src/memory/commit-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AA6BpD,yGAAyG;AACzG,MAAM,MAAM,YAAY;AACtB,sGAAsG;AACpG,OAAO;AACT,6FAA6F;GAC3F,uBAAuB;AACzB;;;;;GAKG;GACD,4BAA4B,CAAC;AAUjC;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAUtD;AAYD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAahE;AAsBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMpE;AAED,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qEAAqE;AACrE,MAAM,WAAW,wBAAwB;IACvC,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,EAAE,YAAY,GAAG,KAAK,CAAC;IAClC,yFAAyF;IACzF,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,yGAAyG;IACzG,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CAmBjF"}