Committing To Git

Committing to Git

Parse JSON status, phase, terminalDisposition, and exit class; keep transaction opaque; show displayText verbatim. Stderr is not the result.

Treat the user's hint as a hypothesis. Use policy, task evidence, and Git facts to correct type and scope, sharpen the outcome, and add useful rationale or user-experience consequences. Do not ask for wording when evidence can improve it.

For a known-context transport-safe subject, the route is workflow prepare -> exact approval and commit authorization -> workflow commit, with no artifact access between helper calls. Drafting authorizes neither staging nor committing; pushing needs separate authorization.

Derive exact scope from task lineage and Git state, never a semantic hint used as a glob, pathspec, prefix, or fuzzy selector. Ask only when two materially different scopes remain plausible. Never autocorrect unmatched selectors.

Prepare

Git 2.45+ lets the helper preflight --no-lazy-fetch and enforce GIT_NO_LAZY_FETCH=1. For a declared read-only .git, request narrow metadata capability before actual preparation or commit. Never delete a live index lock.

Use staged for an intentional index or partial hunks, full for every change, and paths for exact whole paths. Actual paths requires an empty index; draft paths allows only disjoint staged work until cleared. Include rename sides. Manifest inclusion is not review.

Age is not uncertainty. When a targeted exact-path diff fully explains a small dependency, integrity hash, lock entry, or metadata scalar change, use message with read-current-task; do not choose review because it predates this turn.

For mixed provenance, use exact non-overlapping selections covering the scope, not per-file lists. Rationales may overlap; bulk domains may not. Scope verification proves selection, message evidence supports claims, and full review inspects content. Bounded evidence stays inline; larger requirements use packets.

Every mode may write Git objects. Actual full or paths may install the index; drafts do not. Run:

node <skill>/scripts/commitWorkflow.mjs workflow prepare --mode <actual|draft> --scope <staged|full|paths> --evidence <reuse|message|review> --basis <authored-current-task|read-current-task|task-lineage|user-grounded|generated-derived|unknown-preexisting> [--path <literal-path> ...] [--allowed-type <type> ...]

Loaded repository type policy wins. Otherwise choose the most specific dominant outcome: feat capability, fix correction, perf performance, refactor internals, docs, test, build dependencies, ci, or chore maintenance. Do not routinely scan history; sample only an unresolved convention. Disclose only a tie that changes release or user meaning.

Concise eligibility tracks unresolved semantic uncertainty; file count never determines concise eligibility. No path or domain label is an escalation deny-list, including security, migration, deployment, lockfile, generated, or submodule. Escalate only for unresolved evidence or unexplained special Git facts; an explicit review request still stays inline when its complete evidence fits. Oversized inline evidence selects extended, never truncation.

Validate before approval

Complete the message before approval. Checked or structured text must be message-ready; show displayText verbatim. Direct transport requires a known-valid subject. Reapprove only changed bytes or failed-check acknowledgements.

Before presenting any subject for approval, while authoring the first proposal, apply the supported skill message policy: the description immediately after : must begin with an uppercase Unicode cased letter; optional scope does not change this rule. Examples: valid: fix: Tolerate unreachable imports; valid: fix(owl2vowl): Tolerate unreachable imports; invalid: fix: tolerate unreachable imports; invalid: fix(owl2vowl): tolerate unreachable imports. If local validation returns SUBJECT_DESCRIPTION_NOT_CAPITALIZED, correct it before showing the message to the user, avoiding a capitalization-only second approval. This is an authoring defect, not a repository-specific rejection.

Agent-authored bodies or requested inventories use semantic-structure-required and message finalize; nonportable or exact bytes, or a concise subject after review, use fixed message-input.txt and message check. Evidence depth does not determine verbosity. Follow message format and preserve requested sections.

Canonical bytes are strict UTF-8 with one LF. Direct --message is subject + LF only after canUseDirectSubjectTransport() succeeds. Checked text uses the fixed local input:

node <skill>/scripts/commitWorkflow.mjs message check --transaction <opaque-transaction>

Success consumes the input; recreate it for revision. Failure preserves prior valid state and rejected input. Code enforces mechanics, not semantics.

Classify revisions by judgment, not keywords, edit distance, or embeddings.

Complete an extended message

Trust returned reviewRequired and nextAction, not null queue or phase. While required, call workflow review-next cursorless, then with exact reviewProgress.nextCursor. Zero packets means complete; cursorless replay is idempotent. Never open queue paths, hash artifacts manually, or inspect helper source. Use inspection recovery for deletion, binary/gitlink, corruption, or uncertainty.

After review, obey nextAction: author-message uses messagePath with message check; author-content uses contentPath (content.json), versioned contentContract, and message finalize. Preserve schemaVersion, evidenceGroups, and mode. Supported sections are Rationale:, User Experience Changes:, and File Changes:; resolve others before approval and fix aggregate diagnostics by exact JSON pointer together. Detailed applies below 50 units and within 32 KiB; otherwise use bulk. New uncertainty uses fixed evidence-plan-input.json. semantic-structure-required cannot use checked concise text. Convert concise with:

node <skill>/scripts/commitWorkflow.mjs workflow extend --transaction <opaque-transaction> --reason <evidence-uncertainty|semantic-structure-required>
node <skill>/scripts/commitWorkflow.mjs workflow review-next --transaction <opaque-transaction> [--cursor <opaque-cursor>]
node <skill>/scripts/commitWorkflow.mjs message finalize --transaction <opaque-transaction>

For evidence-required, traverse bounded delta, then finalize. authoring-pending means evidence is complete but approval bytes are unavailable; an older revision cannot commit. Optional checks must answer a material unresolved question, not bless a validated scalar.

Promote a draft

Only an unchanged draft may become actual, and only through promotion. It rechecks the attached, detached, or zero-parent unborn head anchor, tree/scope, and staged state; it never authorizes a commit:

node <skill>/scripts/commitWorkflow.mjs workflow promote --transaction <opaque-transaction>

Commit

Optional checks enter the report only through workflow check after preparation and before approval; never reconstruct receipts from prose or output. For diagnostics, failure authorization, drift, detail access, and recovery, read check evidence.

Immediately before this command, confirm commit authorization for the exact displayed bytes and named non-passing receipts. The helper makes one journaled signed transition, compares raw commit-message bytes without trimming, verifies the full OID, and records the report. Never substitute standalone Git steps:

node <skill>/scripts/commitWorkflow.mjs workflow commit --transaction <opaque-transaction> [--message <transport-safe-subject>] [--verification <required|advisory|skipped>] [--acknowledge-failed-check <receipt-id> ...]

Hooks may change the message; preserve the known commit and report the mismatch. For trust-source failure, policy change, or backend identity limits, use signature recovery. One transition reduces duplicate races; journals preserve unknown outcomes without replay.

Interpret, recover, and publish

Resume a recoverably interrupted preparation only with workflow resume --transaction <opaque-transaction>; persisted inputs cannot broaden. Use transaction recovery for permission, lock, partial-phase, or pending/unknown failures. Bounded diagnostics point to a complete hashed failure log. Query count/byte-limited report paths through workflow report-detail; replay the same cursor or cursorless completed page, and use --refresh only for a new observation.

Immediately before publication, obtain separate push authorization for the exact OID, remote, and full destination ref:

node <skill>/scripts/commitWorkflow.mjs workflow publish --transaction <opaque-transaction> --remote <name> --destination <refs/heads/name> [--retry-after-attempt <prior-attempt-id>]

A witnessed success differs from a recovery-time matching remote observation. Never retry automatically: an unchanged ref after a crash remains unknown; confirmed-no-live-child requires explicit user confirmation that the process ended or host restarted. A separately authorized retry binds the prior attempt with --retry-after-attempt. Use publication recovery, workflow verify, workflow recover, workflow cleanup, or workflow report-detail only for named exceptions.