wingfoil 0.2.1

package/dist/memory/frontmatter-edit.js

@@ -0,0 +1,333 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setFrontmatterField = setFrontmatterField;
+exports.removeFrontmatterField = removeFrontmatterField;
+exports.verifyFrontmatterEdit = verifyFrontmatterEdit;
+exports.verifyDocumentEdit = verifyDocumentEdit;
+exports.describeDocumentChanges = describeDocumentChanges;
+/**
+ * Line-based edits of top-level frontmatter fields (task-045-memory-submit).
+ *
+ * Memory transition verbs change a handful of fields — `status` on every verb, `rejection_reason` on
+ * `submit` (removed) and `reject` (set) — per `spec-010-memory-frontmatter-schema`'s field-write
+ * ownership table. Re-serializing the YAML would strip the templates' inline `# REQUIRED …` comments
+ * and normalise quoting everywhere (the defect class of `bug-004` for `dna set`), so these edits touch
+ * only the lines of the one entry being changed and leave every other byte — the rest of the
+ * frontmatter and the whole body — as it was.
+ *
+ * **What "the lines of an entry" are** is decided by YAML's own rules, not by indentation alone (the
+ * first pass's indentation-only rule removed half of a block scalar and folded the rest into the
+ * preceding key — rejection `d7b9d70`). An entry is its column-0 `key:` line plus:
+ *
+ * - a **block scalar** (`|`, `>`, with optional chomping/indentation indicators): every following line
+ *   that is blank or indented at least as far as the scalar's content, `#`-lines included (they are
+ *   content there);
+ * - a **quoted scalar** not closed on the key line: every line up to the closing quote;
+ * - a **plain scalar**: following indented lines that are not comments, with the blank lines between
+ *   them (a plain scalar ends at a comment line);
+ * - an **empty value** (a nested mapping or sequence): following indented or `-` lines, with blank and
+ *   comment lines — at ANY indentation, a column-0 `#` between two column-0 sequence items included —
+ *   only when more of that nested block follows.
+ *
+ * Trailing blank lines, and a comment that ends a value, belong to the parent mapping and are kept.
+ * CRLF documents stay CRLF. Only column-0 keys are matched, so a
+ * nested `status:` or a body line starting with `status:` is never touched.
+ *
+ * A byte-level editor can still be wrong in a case nobody thought of, so {@link verifyFrontmatterEdit}
+ * re-parses the result; the transition verbs refuse to write when it reports a problem.
+ */
+const util_1 = require("util");
+const storage_1 = require("../storage");
+const validation_1 = require("../validation");
+/** Split `content` into the text before the frontmatter lines, those lines, and everything after them. */
+function locateFrontmatter(content) {
+    const { frontmatter } = (0, storage_1.splitFrontmatter)(content);
+    if (frontmatter === null) {
+        throw new Error('document has no frontmatter block');
+    }
+    // `splitFrontmatter` anchors on an opening `---` line, so the frontmatter starts after the first newline.
+    const start = content.indexOf('\n') + 1;
+    return { before: content.slice(0, start), lines: frontmatter.split('\n'), after: content.slice(start + frontmatter.length) };
+}
+// Lines keep a CRLF document's `\r`; every predicate below treats it as trailing whitespace, and the
+// value scan stops before it, so an edited line keeps its ending (see `setFrontmatterField`).
+/**
+ * Join edited frontmatter lines back between `before` and `after`. In a CRLF document the last
+ * frontmatter line's `\r` lives in `after` (`\r\n---`), so a line that becomes last after an edit must
+ * not keep its own `\r`, and a line that stops being last needs one.
+ */
+function assemble(before, lines, after) {
+    const crlf = before.endsWith('\r\n');
+    const joined = lines.map((line, i) => (crlf && i < lines.length - 1 && !line.endsWith('\r') ? `${line}\r` : line)).join('\n');
+    return `${before}${crlf ? joined.replace(/\r$/, '') : joined}${after}`;
+}
+const indentOf = (text) => text.length - text.trimStart().length;
+const isBlank = (text) => text.trim().length === 0;
+const isComment = (text) => text.trimStart().startsWith('#');
+/** Index of the column-0 `key:` line (followed by a space, a tab or the end of the line), or `-1`. */
+function findKeyLine(lines, key) {
+    return lines.findIndex((text) => {
+        const next = text.charAt(key.length + 1);
+        return text.startsWith(`${key}:`) && (next === '' || next === ' ' || next === '\t' || next === '\r');
+    });
+}
+/** Offset of the closing quote in `text` from `from`, honouring `\"` escapes and `''` doubling; `-1` if none. */
+function findClosingQuote(text, from, quote) {
+    for (let i = from; i < text.length; i += 1) {
+        if (quote === '"' && text[i] === '\\') {
+            i += 1;
+        }
+        else if (text[i] === quote) {
+            if (quote === "'" && text[i + 1] === "'") {
+                i += 1;
+            }
+            else {
+                return i;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * The value written on a `key:` line: its text, the offset right after it (where any spaces +
+ * `# comment` begin), and whether it is complete on this line (`false` for a quoted scalar whose
+ * closing quote is on a later line). In a plain value a `#` starts a comment only after whitespace,
+ * so `dr#aft` is one value.
+ */
+function scanHeaderValue(text, key) {
+    let start = key.length + 1;
+    while (text[start] === ' ' || text[start] === '\t')
+        start += 1;
+    const quote = text[start];
+    if (quote === '"' || quote === "'") {
+        const close = findClosingQuote(text, start + 1, quote);
+        return close === -1
+            ? { value: text.slice(start), valueEnd: text.length, closed: false }
+            : { value: text.slice(start, close + 1), valueEnd: close + 1, closed: true };
+    }
+    const comment = quote === '#' ? { index: 0 } : /[ \t]#/.exec(text.slice(start));
+    const end = start + (comment ? comment.index : text.length - start);
+    const valueEnd = start + text.slice(start, end).trimEnd().length;
+    return { value: text.slice(start, valueEnd), valueEnd, closed: true };
+}
+/** The exclusive end index of the entry whose `key:` line is at `index` (rules in the module doc). */
+function entryEnd(lines, index, key) {
+    const header = scanHeaderValue(lines[index], key);
+    const start = index + 1;
+    const block = /^[|>](?:([1-9])[+-]?|[+-]([1-9])?)?$/.exec(header.value);
+    if (block) {
+        const explicit = block[1] ?? block[2];
+        const firstContent = lines.slice(start).find((text) => !isBlank(text));
+        const contentIndent = explicit !== undefined ? Number(explicit) : indentOf(firstContent ?? '');
+        let end = start;
+        let lastContent = start;
+        while (contentIndent > 0 && end < lines.length) {
+            const text = lines[end];
+            if (!isBlank(text) && indentOf(text) < contentIndent)
+                break;
+            end += 1;
+            if (!isBlank(text))
+                lastContent = end;
+        }
+        return lastContent;
+    }
+    if (!header.closed) {
+        const quote = header.value.charAt(0);
+        const closing = lines.slice(start).findIndex((text) => findClosingQuote(text, 0, quote) !== -1);
+        return closing === -1 ? lines.length : start + closing + 1;
+    }
+    const nested = header.value.length === 0;
+    let lastContent = start;
+    for (let end = start; end < lines.length; end += 1) {
+        const text = lines[end];
+        // Inside a nested value a comment line continues the block whatever its indentation: a column-0
+        // `#` between two column-0 sequence items is part of that sequence, not the end of the entry
+        // (`bug-041` G2, whose removal left `- b` orphaned behind the deleted key — invalid YAML).
+        // `lastContent` still advances only on real content, so a comment that *ends* the value is not
+        // swallowed: it belongs to the parent mapping and is kept.
+        if (isBlank(text) || (nested && isComment(text)))
+            continue;
+        const child = indentOf(text) > 0 || (nested && text.startsWith('-'));
+        if (!child || isComment(text))
+            break;
+        lastContent = end + 1;
+    }
+    return lastContent;
+}
+/** State-machine identifiers and other simple tokens YAML reads back as the same string, unquoted. */
+const PLAIN_SAFE = /^[A-Za-z][A-Za-z0-9._/-]*$/;
+const YAML_TYPED_WORD = /^(?:true|false|yes|no|on|off|y|n|null)$/i;
+/**
+ * Serialize `value` as a YAML scalar that parses back to exactly `value`: a plain token when that is
+ * unambiguous (so `status: pending` stays a one-token diff), otherwise a JSON string literal — every
+ * JSON string escape is also a valid YAML double-quoted escape, so quotes, colons, `#`, newlines and
+ * leading/trailing whitespace all survive (task-047's `rejection_reason` carries arbitrary text).
+ */
+function toYamlScalar(value) {
+    return PLAIN_SAFE.test(value) && !YAML_TYPED_WORD.test(value) ? value : JSON.stringify(value);
+}
+/**
+ * Set top-level `key` to the string `value`, serialized YAML-safely. An existing entry is replaced as a
+ * whole — continuation lines, block-scalar body or multi-line quoted value included. A `# comment` on
+ * the key line is kept when the old value ended on that line; the line ending of the key line is kept.
+ * An absent key is appended after the last non-blank frontmatter line, with the document's line ending.
+ *
+ * @throws `Error` when the document has no frontmatter block.
+ */
+function setFrontmatterField(content, key, value) {
+    const { before, lines, after } = locateFrontmatter(content);
+    const entry = `${key}: ${toYamlScalar(value)}`;
+    const index = findKeyLine(lines, key);
+    if (index === -1) {
+        // After the last NON-BLANK line, not simply last: trailing blank lines can belong to a
+        // keep-chomped (`|+`) block scalar's value, and pushing the new key past them would change that
+        // other field — which the post-condition then rightly refuses (`bug-041` G3).
+        let at = lines.length;
+        while (at > 0 && isBlank(lines[at - 1]))
+            at -= 1;
+        return assemble(before, [...lines.slice(0, at), entry, ...lines.slice(at)], after);
+    }
+    const header = lines[index];
+    const { valueEnd, closed } = scanHeaderValue(header, key);
+    // A value that ended on the key line keeps what followed it there (spaces, `# comment`); line
+    // endings are restored by `assemble`. A tail that starts at the `#` itself — the shape an EMPTY
+    // value with an inline comment leaves behind (`rejection_reason:   # set by memory.reject`) — gets
+    // a separating space: `value# comment` is a comment YAML requires to be preceded by whitespace, and
+    // js-yaml's tolerance of it hid the defect from the re-parse post-condition (`bug-041` G1).
+    const tail = closed ? header.slice(valueEnd) : '';
+    const separated = tail.startsWith('#') ? ` ${tail}` : tail;
+    return assemble(before, [...lines.slice(0, index), `${entry}${separated}`, ...lines.slice(entryEnd(lines, index, key))], after);
+}
+/**
+ * Remove top-level `key` together with every line its value spans (rules in the module doc). Blank
+ * lines and comments that follow the value belong to the parent mapping and are kept. Returns `content`
+ * unchanged when the key is absent.
+ *
+ * @throws `Error` when the document has no frontmatter block.
+ */
+function removeFrontmatterField(content, key) {
+    const { before, lines, after } = locateFrontmatter(content);
+    const index = findKeyLine(lines, key);
+    if (index === -1)
+        return content;
+    return assemble(before, [...lines.slice(0, index), ...lines.slice(entryEnd(lines, index, key))], after);
+}
+/** Parse a document's frontmatter into a plain record, or return why it cannot be. */
+function parseFrontmatter(content) {
+    const { frontmatter } = (0, storage_1.splitFrontmatter)(content);
+    if (frontmatter === null)
+        return 'rendered document has no frontmatter block';
+    try {
+        const parsed = (0, validation_1.parseYaml)(frontmatter, 'frontmatter');
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch (error) {
+        if (!(error instanceof validation_1.ValidationError))
+            throw error;
+        return `rendered frontmatter is not valid YAML: ${error.issues.map((issue) => issue.message).join('; ')}`;
+    }
+}
+/**
+ * The post-condition of a frontmatter edit, checked by re-parsing rather than by trusting the editor.
+ * `expected` maps each field the operation owns to its required value (`undefined` = must be absent).
+ * Returns the problems found, empty when the edit is sound:
+ *
+ * - the rendered document has no frontmatter, or it does not parse;
+ * - an owned field does not have its expected value, or is still present when it should be removed;
+ * - any **other** field's parsed value differs from `before` — an edit leaked into a field it does not own.
+ *
+ * Deterministic (REQ-SYS-07): owned fields in `expected`'s order, then other fields sorted by name.
+ */
+function verifyFrontmatterEdit(before, after, expected) {
+    const rendered = parseFrontmatter(after);
+    if (typeof rendered === 'string')
+        return [rendered];
+    const parsedBefore = parseFrontmatter(before);
+    const original = typeof parsedBefore === 'string' ? {} : parsedBefore;
+    return [...ownedFieldProblems(rendered, expected), ...unownedFieldProblems(original, rendered, expected)];
+}
+/** Each field the operation owns that does not hold its expected value (`undefined` = must be absent). */
+function ownedFieldProblems(rendered, expected) {
+    const problems = [];
+    for (const [field, value] of Object.entries(expected)) {
+        if (value === undefined) {
+            if (field in rendered)
+                problems.push(`field '${field}' is still present, expected it removed`);
+        }
+        else if (rendered[field] !== value) {
+            problems.push(`field '${field}' is ${JSON.stringify(rendered[field])}, expected ${JSON.stringify(value)}`);
+        }
+    }
+    return problems;
+}
+/** Each field the operation does NOT own whose parsed value moved. Sorted by name (REQ-SYS-07). */
+function unownedFieldProblems(original, rendered, expected) {
+    const problems = [];
+    const others = [...new Set([...Object.keys(original), ...Object.keys(rendered)])].filter((field) => !(field in expected)).sort();
+    for (const field of others) {
+        if (!(0, util_1.isDeepStrictEqual)(original[field], rendered[field])) {
+            problems.push(`field '${field}' changed although this operation does not own it`);
+        }
+    }
+    return problems;
+}
+/**
+ * The post-condition of a whole-document edit: {@link verifyFrontmatterEdit}'s frontmatter rules plus
+ * the body, gated by `scope`. Returns the problems found, empty when the edit is within scope.
+ *
+ * Under `carries-content` only the `expected` fields are checked — every other field and the body are
+ * the operation's to write. Under `declared-fields-only` an unowned field or a changed body is a
+ * problem, which is the rule `bug-076` showed nothing was enforcing.
+ *
+ * Deterministic (REQ-SYS-07): owned fields in `expected`'s order, then other fields sorted by name,
+ * then the body.
+ */
+function verifyDocumentEdit(before, after, expected, scope) {
+    const rendered = parseFrontmatter(after);
+    if (typeof rendered === 'string')
+        return [rendered];
+    const problems = ownedFieldProblems(rendered, expected);
+    if (scope === 'carries-content')
+        return problems;
+    const parsedBefore = parseFrontmatter(before);
+    problems.push(...unownedFieldProblems(typeof parsedBefore === 'string' ? {} : parsedBefore, rendered, expected));
+    if ((0, storage_1.splitFrontmatter)(before).body !== (0, storage_1.splitFrontmatter)(after).body) {
+        problems.push('the body changed although this operation does not own it');
+    }
+    return problems;
+}
+/**
+ * Name, in a form a person can act on, every way `after` differs from `before` — the frontmatter
+ * fields whose parsed value moved, and whether the body moved. `before` is `null` when the document
+ * does not exist at the revision being compared against.
+ *
+ * This is the *reporting* half of {@link verifyDocumentEdit}: the verifier answers "is this edit in
+ * scope", this answers "so what exactly is in the way". A difference that changes no parsed value and
+ * no body byte — a reordered comment, a requoted scalar — is still a difference git will commit, so
+ * it is reported as such rather than dropped.
+ *
+ * Deterministic (REQ-SYS-07): fields sorted by name, then the frontmatter-text fallback, then the body.
+ */
+function describeDocumentChanges(before, after) {
+    if (before === null)
+        return ['the document is not tracked at HEAD'];
+    if (before === after)
+        return [];
+    const parsedBefore = parseFrontmatter(before);
+    const parsedAfter = parseFrontmatter(after);
+    const original = typeof parsedBefore === 'string' ? {} : parsedBefore;
+    const rendered = typeof parsedAfter === 'string' ? {} : parsedAfter;
+    const changes = [...new Set([...Object.keys(original), ...Object.keys(rendered)])]
+        .sort()
+        .filter((field) => !(0, util_1.isDeepStrictEqual)(original[field], rendered[field]))
+        .map((field) => `frontmatter field '${field}'`);
+    const beforeSplit = (0, storage_1.splitFrontmatter)(before);
+    const afterSplit = (0, storage_1.splitFrontmatter)(after);
+    if (changes.length === 0 && beforeSplit.frontmatter !== afterSplit.frontmatter) {
+        changes.push('the frontmatter text (comments or formatting)');
+    }
+    if (beforeSplit.body !== afterSplit.body)
+        changes.push('the body');
+    return changes.length > 0 ? changes : ['the file content'];
+}
+//# sourceMappingURL=frontmatter-edit.js.map

package/dist/memory/frontmatter-edit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-edit.js","sourceRoot":"","sources":["../../src/memory/frontmatter-edit.ts"],"names":[],"mappings":"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"}

package/dist/memory/git-log.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Run `git log <extraArgs> --format=<each field followed by %x00> -- <pathspecs>` and return each
+ * matching commit's raw field list (in `fields` order, not yet destructured into a named shape —
+ * that's each caller's concern), oldest first.
+ *
+ * Because the field and record delimiters are the same character ({@link NUL}), records are
+ * recovered by **arity** rather than by a second delimiter: the stream is split on NUL and consumed
+ * in fixed groups of `fields.length`. That is what makes the walk independent of its own output's
+ * content — there is no character a commit could carry that would realign the groups — and it also
+ * means a field that is legitimately empty (a commit with no body, `%b`) still occupies its slot
+ * instead of being dropped. **Every returned record therefore has exactly `fields.length` entries**
+ * — a partial group at the end of the stream is not a record and is discarded, never padded — which
+ * is the postcondition `./history`'s destructuring relies on.
+ *
+ * git terminates each commit's formatted output with a newline. The format ends with a delimiter, so
+ * that newline falls in the piece AFTER the record's last field — which is why the split's final
+ * piece is dropped rather than grouped. Dropping it explicitly, instead of letting it fall off as a
+ * short remainder, is what makes the walk total at **one** field too: at that arity the tail is a
+ * whole group of its own and became a spurious record (it did, on this task's first pass; the
+ * arity-1 cases in `test/memory/git-log-framing.test.ts` now pin it). What survives of the newline is
+ * a single leading `\n` on each record's first field after the first, and that is stripped; both call
+ * sites put `%H` first, which never legitimately begins with one.
+ *
+ * Returns `[]` — never throws — both when `root` is not a git repository at all and when none of
+ * `pathspecs` has any matching history; "not a repo"/"not found" is a caller concern, not this
+ * primitive's (mirrors `getMemoryHistory`'s original contract). That now holds at EVERY arity: with
+ * no matching commits git prints nothing, the split yields one piece, and dropping it leaves nothing
+ * to group. An empty `fields` requests nothing and likewise yields `[]`, rather than looping forever
+ * over zero-width groups.
+ */
+export declare function walkGitLogFields(root: string, fields: readonly string[], pathspecs: readonly string[], extraArgs?: readonly string[]): string[][];
+//# sourceMappingURL=git-log.d.ts.map

package/dist/memory/git-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-log.d.ts","sourceRoot":"","sources":["../../src/memory/git-log.ts"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,SAAS,GAAE,SAAS,MAAM,EAAO,GAChC,MAAM,EAAE,EAAE,CA6BZ"}

package/dist/memory/git-log.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.walkGitLogFields = walkGitLogFields;
+/**
+ * Shared low-level `git log` field walk (task-015-complete-audit-trail refactor) — task-011's
+ * `./history` (`getMemoryHistory`) and this task's `./audit` (`auditAttribution`) both need the same
+ * "run `git log` with a custom multi-field format, split stdout into per-commit records, oldest
+ * first" plumbing over a different field set/pathspec shape; this is that one shared primitive, so
+ * the record-separator convention lives in exactly one place instead of being copy-pasted twice.
+ */
+const child_process_1 = require("child_process");
+/**
+ * The `--format` placeholder git expands to a single NUL byte, used to delimit BOTH the fields of a
+ * commit and one commit's record from the next. A literal NUL cannot be written into the format
+ * string, because it travels to git through `argv` and a C string ends at the first NUL — so `%x00`
+ * is the only way to get one there at all.
+ */
+const NUL_PLACEHOLDER = '%x00';
+/**
+ * The delimiter {@link NUL_PLACEHOLDER} expands to, and the one character this module splits on.
+ *
+ * The guarantee, stated as narrowly as it actually holds
+ * (`task-086-fix-reason-control-chars-history-forgery`, `bug-050`): **git refuses to write a commit
+ * whose message contains a NUL byte** — `error: a NUL byte in commit log message not allowed`,
+ * raised by every writer down to `commit-tree`, the lowest-level plumbing there is. This is not a
+ * claim about what commit text conventionally contains; it is a property git enforces at write time,
+ * and it is the same property git's own `-z` output options rest on.
+ * `test/memory/git-log-framing.test.ts` pins it against all three writers rather than trusting it.
+ *
+ * It replaced a pair of separators (`0x1f`/`0x1e`) documented as characters "a real commit
+ * subject/body never contains". That claim was false by construction: `--reason <text>` is arbitrary
+ * free text that lands in the commit body (P1.7/P1.8, REQ-SEC-04), so a reason carrying `0x1e` split
+ * one commit's record in two and made `wingfoil memory history` (P1.10) print a fabricated entry
+ * whose `sha` was the caller-supplied text, while the genuine approval lost its `from`. Because the
+ * delimiters live in the `--format` string — expanded by git at READ time and never stored — moving
+ * to NUL re-reads all history under the new framing, whenever and by whichever writer it was made.
+ *
+ * Built with `String.fromCharCode` rather than spelled as a unicode escape for code point zero,
+ * because any tool that resolves such an escape while editing this file leaves a RAW NUL byte in
+ * the source — at which point git classifies the file as binary and stops diffing it. Observed
+ * once here, hence the note: the constructor form cannot be resolved into the file by accident.
+ */
+const NUL = String.fromCharCode(0);
+/**
+ * Run `git log <extraArgs> --format=<each field followed by %x00> -- <pathspecs>` and return each
+ * matching commit's raw field list (in `fields` order, not yet destructured into a named shape —
+ * that's each caller's concern), oldest first.
+ *
+ * Because the field and record delimiters are the same character ({@link NUL}), records are
+ * recovered by **arity** rather than by a second delimiter: the stream is split on NUL and consumed
+ * in fixed groups of `fields.length`. That is what makes the walk independent of its own output's
+ * content — there is no character a commit could carry that would realign the groups — and it also
+ * means a field that is legitimately empty (a commit with no body, `%b`) still occupies its slot
+ * instead of being dropped. **Every returned record therefore has exactly `fields.length` entries**
+ * — a partial group at the end of the stream is not a record and is discarded, never padded — which
+ * is the postcondition `./history`'s destructuring relies on.
+ *
+ * git terminates each commit's formatted output with a newline. The format ends with a delimiter, so
+ * that newline falls in the piece AFTER the record's last field — which is why the split's final
+ * piece is dropped rather than grouped. Dropping it explicitly, instead of letting it fall off as a
+ * short remainder, is what makes the walk total at **one** field too: at that arity the tail is a
+ * whole group of its own and became a spurious record (it did, on this task's first pass; the
+ * arity-1 cases in `test/memory/git-log-framing.test.ts` now pin it). What survives of the newline is
+ * a single leading `\n` on each record's first field after the first, and that is stripped; both call
+ * sites put `%H` first, which never legitimately begins with one.
+ *
+ * Returns `[]` — never throws — both when `root` is not a git repository at all and when none of
+ * `pathspecs` has any matching history; "not a repo"/"not found" is a caller concern, not this
+ * primitive's (mirrors `getMemoryHistory`'s original contract). That now holds at EVERY arity: with
+ * no matching commits git prints nothing, the split yields one piece, and dropping it leaves nothing
+ * to group. An empty `fields` requests nothing and likewise yields `[]`, rather than looping forever
+ * over zero-width groups.
+ */
+function walkGitLogFields(root, fields, pathspecs, extraArgs = []) {
+    if (fields.length === 0)
+        return [];
+    const format = fields.map((field) => `${field}${NUL_PLACEHOLDER}`).join('');
+    let stdout;
+    try {
+        stdout = (0, child_process_1.execFileSync)('git', ['-C', root, 'log', ...extraArgs, `--format=${format}`, '--', ...pathspecs], { encoding: 'utf-8' });
+    }
+    catch {
+        return [];
+    }
+    // The stream is `<f1>NUL<f2>NUL…<fn>NUL` per commit, each run terminated by git's own newline, so
+    // the text after the FINAL NUL is never a field — it is that newline, or the empty string when git
+    // printed nothing at all. Drop it before grouping; at `fields.length === 1` it would otherwise be
+    // a complete group and become a record that no commit backs. Only whole groups of `fields.length`
+    // are records thereafter.
+    const pieces = stdout.split(NUL);
+    pieces.pop();
+    const records = [];
+    for (let index = 0; index + fields.length <= pieces.length; index += fields.length) {
+        const record = pieces.slice(index, index + fields.length);
+        record[0] = record[0].replace(/^\n+/, '');
+        records.push(record);
+    }
+    return records.reverse();
+}
+//# sourceMappingURL=git-log.js.map

package/dist/memory/git-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-log.js","sourceRoot":"","sources":["../../src/memory/git-log.ts"],"names":[],"mappings":";;AAyEA,4CAkCC;AA3GD;;;;;;GAMG;AACH,iDAA6C;AAE7C;;;;;GAKG;AACH,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,gBAAgB,CAC9B,IAAY,EACZ,MAAyB,EACzB,SAA4B,EAC5B,YAA+B,EAAE;IAEjC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,GAAG,eAAe,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5E,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAA,4BAAY,EACnB,KAAK,EACL,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,SAAS,EAAE,YAAY,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC,EAC3E,EAAE,QAAQ,EAAE,OAAO,EAAE,CACtB,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,kGAAkG;IAClG,mGAAmG;IACnG,kGAAkG;IAClG,kGAAkG;IAClG,0BAA0B;IAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,CAAC,GAAG,EAAE,CAAC;IACb,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QACnF,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC1D,MAAM,CAAC,CAAC,CAAC,GAAI,MAAM,CAAC,CAAC,CAAY,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACtD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;AAC3B,CAAC"}

package/dist/memory/history.d.ts

@@ -0,0 +1,142 @@
+/** One commit touching a Memory document, in the shape `wingfoil memory history` will render from. */
+export interface MemoryHistoryEntry {
+    readonly sha: string;
+    readonly authorName: string;
+    readonly authorEmail: string;
+    /** Author date, ISO-8601 (`git log --format=%aI`) — never the commit/system date. */
+    readonly date: string;
+    readonly subject: string;
+    readonly body: string;
+    /**
+     * The root-relative path the document occupied **at this commit**, which is not in general the
+     * path the caller asked for: the walk follows renames, so a commit older than one holds the
+     * element under its former name ({@link collectHistoricalPaths}).
+     *
+     * Carried on the entry rather than recomputed by each consumer, because the walk is the only thing
+     * that knows it — `git log --follow --name-status` reports every `R<score> <old> <new>` edge it
+     * crosses. A reader that instead asks git for the CURRENT path at every sha gets nothing back at
+     * the pre-rename ones, which is
+     * `bug-080-read-status-at-reads-the-current-path-at-pre-rename-commits`
+     * (`task-097-memory-history-reads-each-commit-at-its-historical-path`).
+     */
+    readonly path: string;
+}
+/**
+ * The sha of the commit that introduced `relativePath` as a COPY of a file that outlives it — the
+ * element's own creation — or `null` when the followed chain contains no copy edge at all.
+ *
+ * This is the distinction the fix turns on. `git log --follow` can change path across two different
+ * kinds of edge, and they mean opposite things for an audit trail:
+ *
+ *  - **`R` (rename)** — the element continuing under a new name. Keep following. This is not a
+ *    hypothetical requirement: `docs/self/docs/04_memory/planning/v1/*` became `planning/rl-v1/*` in
+ *    one commit in this repository, moving five `release` elements at once, because the `release`
+ *    type's `path` pattern interpolates the release-line id (`memory.yaml`). For one of them a plain
+ *    `git log -- <path>` returns a single commit where the followed walk returns seven, so dropping
+ *    `--follow` would delete five sixths of that element's recorded history.
+ *  - **`C` (copy)** — the element being born out of a file that still exists. `wingfoil memory add`
+ *    copies the type's template verbatim (CLAUDE.md §5.1), and `wingfoil init` has already committed
+ *    that template, so this edge is how every scaffolded element begins. Everything strictly older
+ *    than it is the template's history, not the element's.
+ *
+ * Only the newest copy edge matters — it is the element's own creation; any older one belongs to
+ * whatever the source itself was copied from. `git log` prints newest first, so that is the first
+ * line.
+ *
+ * **Throws** — never returns `null` — when git itself fails. "git could not answer" and "this
+ * element was never copied from anything" are different answers, and collapsing the first into the
+ * second would silently restore the phantom entry; it is also why this cannot borrow
+ * `walkGitLogFields`, whose `catch` returns `[]` (`bug-072-oversized-git-log-becomes-empty-history`).
+ * {@link getMemoryHistory} calls this only once the main walk has already returned commits, so at
+ * that point the repository and the path are both known good and a failure here is genuinely
+ * exceptional.
+ *
+ * @param root - Absolute path of the repository to walk.
+ * @param relativePath - The element's root-relative path, as {@link getMemoryHistory} takes it.
+ * @returns The creation commit's full sha, or `null` when the chain has no copy edge.
+ */
+export declare function findElementCreationSha(root: string, relativePath: string): string | null;
+/**
+ * Drop the part of an oldest-first walk that precedes the element's creation, keeping the creation
+ * commit itself — the ancestry `--follow` reached through a copy edge, which belongs to the file the
+ * element was copied from. `creationSha` of `null` (no copy edge: the document was authored in
+ * place) leaves the walk untouched.
+ *
+ * Pure: no git, no filesystem. Separated from {@link findElementCreationSha} so the truncation rule
+ * and the invariant below are exercised directly rather than through a repository fixture.
+ *
+ * **Throws** when `creationSha` is absent from `entries`. The two walks are the same walk — one is
+ * the other filtered by git — so a sha in the narrower one that is missing from the wider one is a
+ * broken invariant, not a case to absorb. Defaulting to "no truncation" there would report the
+ * phantom entry again while reporting success.
+ *
+ * @param entries - The full `--follow` walk, oldest first.
+ * @param creationSha - The element's creation commit, from {@link findElementCreationSha}.
+ * @returns `entries` from the creation commit onward (a new array; `entries` is not mutated).
+ */
+export declare function dropPreCreationAncestry(entries: readonly MemoryHistoryEntry[], creationSha: string | null): MemoryHistoryEntry[];
+/**
+ * Where `relativePath`'s document lived at each commit of its `--follow` walk, keyed by sha.
+ *
+ * `git log --follow --name-status` prints, per commit, the sha then that commit's status line for
+ * the followed path — `A <path>`, `M <path>`, `D <path>`, or `R<score> <old> <new>` at a rename. The
+ * path the file occupies **at** a commit is always the LAST tab-separated field of that line: the
+ * destination of a rename, the single path otherwise. Everything older than that rename then reports
+ * the old path, which is the whole point — it is what
+ * `git show <sha>:<path>` needs in order to resolve at all.
+ *
+ * A commit git reports no status line for (it shows no diff for a merge without `-m`) is simply
+ * absent from the map; {@link attachHistoricalPaths} decides what to do about that, so the rule is
+ * testable without a repository.
+ *
+ * **Throws** — never returns an empty map — when git itself fails, for the same reason
+ * {@link findElementCreationSha} does: "git could not answer" and "this element was never renamed"
+ * are different answers, and folding the first into the second silently reinstates `bug-080` by
+ * reading every commit at the current path again. {@link getMemoryHistory} calls this only once the
+ * main walk has returned commits, so the repository and the path are both known good by then.
+ *
+ * @param root - Absolute path of the repository to walk.
+ * @param relativePath - The element's current root-relative path, as the caller named it.
+ * @returns sha → the root-relative path the document occupied at that commit.
+ */
+export declare function collectHistoricalPaths(root: string, relativePath: string): Map<string, string>;
+/**
+ * Stamp each walked commit with the path the element occupied at it, from
+ * {@link collectHistoricalPaths}' map.
+ *
+ * Pure: no git, no filesystem — separated from the probe for the same reason
+ * {@link dropPreCreationAncestry} is separated from {@link findElementCreationSha}, so the rule and
+ * its fallback are exercised directly rather than through a repository fixture.
+ *
+ * Falls back to `fallbackPath` (the path the caller named) for a sha the probe reported no diff for,
+ * rather than throwing: unlike the creation probe's invariant, an absent entry here is not evidence
+ * of a broken walk — git shows no diff for a merge commit — and the fallback is precisely the
+ * behaviour that shipped before this field existed, so it can degrade no further than the status quo.
+ *
+ * @param entries - The `--follow` walk, oldest first.
+ * @param pathBySha - sha → historical path, from {@link collectHistoricalPaths}.
+ * @param fallbackPath - The element's current root-relative path.
+ * @returns A new array; `entries` is not mutated.
+ */
+export declare function attachHistoricalPaths(entries: readonly MemoryHistoryEntry[], pathBySha: ReadonlyMap<string, string>, fallbackPath: string): MemoryHistoryEntry[];
+/**
+ * Walk every commit that touched `relativePath`, oldest first (P1.10-memory-history.feature: "lists
+ * ... entries in chronological order") — `git log` itself returns newest-first, reversed by
+ * {@link walkGitLogFields} — and only those commits. The walk follows renames, so an element moved on
+ * disk keeps its history, but stops at the element's own creation rather than continuing into the
+ * template it was copied from ({@link findElementCreationSha}).
+ *
+ * Returns `[]`, rather than throwing, both when `root` has no commits touching the path at all and
+ * when `root` is not a git repository — "document not found" is a caller/feature-layer concern
+ * (task-021/026-style CLI error rendering), not this primitive's. That is also why the creation
+ * probe runs only on a non-empty walk: on an empty one there is nothing to truncate and nothing to
+ * conclude from git's silence — and the same for the path probe.
+ *
+ * Every returned entry carries the path the element occupied at its own commit
+ * ({@link MemoryHistoryEntry.path}), not the one the caller named. That is what makes this walk the
+ * single source of truth for "where was this file at this commit": a consumer that reads content per
+ * commit — `./audit`'s `reconstructMemoryTransitions`, which reads the frontmatter `status:` — must
+ * take the path from here rather than re-using its own argument (`bug-080`).
+ */
+export declare function getMemoryHistory(root: string, relativePath: string): MemoryHistoryEntry[];
+//# sourceMappingURL=history.d.ts.map