T-TH9J-git-log-machine-parseable-format-convention

Status: closed/superseded · Impact: low · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to open/ready before picking up.

Goal

Plugin scripts that consume git log output (e.g. plugin/skills/task-work/check_ancestry.ts) need a single canonical format string. The first script picked %H%n%s (sha + newline + subject) per the spec in T-WKQD-task-work-ancestry-helper-one-liner and the implementer switched to %H%x09%s (tab-separated, single line per commit) for robustness. The next script will face the same choice without guidance. A short convention doc would set the default and prevent the drift.

Today

plugin/skills/task-work/check_ancestry.ts parses git log --format=%H%x09%s and splits on the first tab. No other script under plugin/ consumes git log output today, so the choice is unanchored — a second author writing a similar helper has no canonical to reference. The T-WKQD-task-work-ancestry-helper-one-liner task spec said %H%n%s and the implementation diverged.

Proposed

A short doc at plugin/conventions/git-log-machine-parseable.md that states:

• Default to --format=%H%x09%s (tab-separated) for one-line-per-commit records.
• Use %x1f (ASCII unit separator) instead of tab when commit subjects might contain tabs.
• Use --format=%H%n%B%n%x00 (NUL-terminated bodies) when the full commit message body is needed; parse with split('\0').
• Always pair the format with git -c log.showSignature=false to suppress signature output that would otherwise interleave.

Each plugin/skills/<skill>/SKILL.md that talks about parsing git log output references the convention doc in its ## Notes block per plugin/skills/CLAUDE.md.

Approach

1. Write plugin/conventions/git-log-machine-parseable.md with the three format-string recipes above and a one-paragraph rationale for each.
2. Update plugin/skills/task-work/check_ancestry.ts’s docstring to cite the convention (one-line link in the module docstring).
3. Optionally: lint for divergent format strings via plugin/scripts/lint_skill_prose.ts once a second consumer exists; until then the convention is documentation-only.

Files to touch

Location	Kind	Change
plugin/conventions/git-log-machine-parseable.md (new)	new	the
plugin/skills/task-work/check_ancestry.ts	modify	add a one-line cite

Acceptance criteria

• AC-1: A new doc exists at plugin/conventions/git-log-machine-parseable.md enumerating the three format recipes (%H%x09%s, %x1f-separated, NUL-terminated) with a one-paragraph rationale each.
• AC-2: plugin/skills/task-work/check_ancestry.ts’s module docstring cites the new convention doc.

Out of scope

• A linter that enforces the convention across the plugin. The convention starts as documentation; promote to a lint rule only once a second consumer of git log exists.
• Convention coverage for git for-each-ref, git rev-list, or other plumbing commands. This doc is scoped to git log parsing.

Dependencies

• none

Discovery context

Spawned by /sdlc:task-work post-mortem of T-WKQD-task-work-ancestry-helper-one-liner on 2026-05-21.

---

← Back to Tasks