targeted-artifact-commit-verification

name	targeted-artifact-commit-verification
description	Verify whether the exact files from a just-completed task are still uncommitted before creating another commit, especially in dirty repos with unrelated churn.
version	1.0.0
tags	["git","commit","verification","dirty-repo","handoff"]

Targeted Artifact Commit Verification

Use when:

• the repo has lots of unrelated modified/untracked files
• the user asks to commit work from the current task
• you need to avoid creating a duplicate/no-op commit
• you suspect an auto-sync or prior commit may have already landed the exact artifacts

Why this exists

In a dirty checkout, git status --short alone can mislead you into thinking your task artifacts still need committing when only unrelated files remain dirty.

A reliable pattern is to verify the exact task artifact set before staging or committing.

Workflow

1. Identify the exact task files. Example:

   • analysis/provider-session-ecosystem-audit.json
   • docs/reports/provider-session-ecosystem-audit.md
   • docs/reports/2026-04-23-provider-session-learning-transfer.md

2. Check only those files for remaining diff. Run:

   • git status --short -- <files...>
   • git diff --stat -- <files...>

3. If both are empty, do not create a new commit yet. Treat this as a possible already-committed state, not a failure.

4. Confirm the files are tracked and identify the commit that already contains them. Run:

   • git ls-files --error-unmatch <files...>
   • git log --oneline -n 5 -- <files...>
   • if needed, git show --stat --name-only --oneline <sha> -- <files...>

5. Only create a new commit if the targeted files still have real uncommitted changes.

Binary/report artifact extension

When the artifact is a generated report copy, DOCX/PDF, or other binary under an outputs/-style tree, verify both git state and artifact usability before claiming it landed:

• Do not rely only on file-search tools; ignored/generated paths may be omitted from indexed search. Probe exact expected paths with [ -e <path> ], stat, and git ls-files <path>.
• Confirm the canonical report sibling names, e.g. *_report.html, *_client_review.docx, and *.pdf, so follow-up work starts from the right artifact rather than a guessed basename.
• After push, fetch the raw GitHub URL with curl -L -w '%{http_code}' and validate the returned size/content, not just local existence.
• For DOCX replacements, parse the remote DOCX with python-docx/zip inspection and report structural evidence such as paragraph count, native table count, and word/media/* count. This distinguishes native editable Word output from page-image PDF conversions.
• Include the issue-comment URL and commit SHA in closeout evidence when a GitHub issue is the coordination record.

Exit/handoff extension

If the target artifacts are already committed but the repo is still dirty:

• explicitly tell the user the requested task artifacts are already committed
• name the commit SHA and subject
• distinguish unrelated remaining churn from the completed task artifacts
• if the user asks to prepare for exit, create a handoff doc rather than forcing another commit for the same files

Recommended wording

• "The files from this task are already in commit <sha>; there is no remaining diff for them."
• "The repo is still dirty, but the remaining changes are unrelated to the completed artifact set."

Pitfalls

• Do not rely on repo-wide git status when the task only touched a few files.
• Do not create a second commit just because the worktree is dirty.
• Do not assume a newly written file is uncommitted; auto-sync or a prior commit may already include it.