commit

name	commit
description	Commit changes with govctl integration — check work item status, preserve durable notes only when needed, and run govctl check
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, TodoWrite
argument-hint	[optional commit message hint]

/commit — Commit with Govctl Integration

Commit changes using the project's version control system, with govctl-aware checks.

Outputs: Recorded VCS commit, updated work-item memory when applicable, and a clean post-commit working copy.

---

WORKFLOW

CRITICAL: Steps MUST be executed in exact order. Do NOT skip ahead.

1. This is the only workflow that should issue raw jj or git commit commands.
2. Do not perform RFC/ADR lifecycle verbs here, except work-item tick/move updates and rare durable notes that belong to commit bookkeeping.
3. Implementation-bearing commits should belong to an active work item.
4. Spec-only governance commits may proceed without a work item only when the diff is limited to governance artifacts, rendered governance docs, embedded skill/agent templates, or related metadata.

Step 1: Detect VCS and Governance

1a. Detect VCS. Run jj root first. If it succeeds, use Jujutsu — do NOT also check git. A jj-git colocated repo has both .jj/ and .git/, so checking git would also succeed and cause you to use the wrong VCS. Only if jj root fails, run git rev-parse --git-dir. If that succeeds, use Git. If both fail, stop and inform user.

CRITICAL: Do NOT run jj root and git rev-parse in parallel. Run jj root first, and only proceed to git detection if jj is not found.

1b. Detect governance. Check whether the current repository is governed by govctl:

test -f gov/config.toml || test -d gov

• If governed (exit 0): continue with Steps 2–7 as written below.
• If not governed (exit 1): skip all govctl-specific steps (Steps 2–3 and 7). Proceed directly to Step 4 (Inspect Changes), then Step 5 (Compose Message), then Step 6 (Execute Commit) using plain VCS commands. Omit work-item tracking and govctl check entirely. Mention in your summary that no govctl governance was detected.

Step 2: Govctl Pre-Commit Checks

Before committing, run govctl checks:

govctl check

If check fails, stop. Show the diagnostics, fix the issue, and rerun govctl check before committing.

Step 3: Work Item Status Check

Check for queued and active work items:

govctl work list pending

If an active work item exists:

1. Determine whether the active work item actually matches this diff.
2. If the diff is spec-only governance maintenance unrelated to the active work item, the commit may remain work-item-free even while another work item is active.
3. If the active work item applies, then:
   • Ask whether any closure-worthy durable notes should be recorded; skip notes for progress, validation output, review status, next actions, temporary blockers, or TODOs
   • Check whether any acceptance criteria can be ticked:

     govctl work show <WI-ID>
     

     If criteria match the completed work, suggest ticking them:

     govctl work tick <WI-ID> acceptance_criteria "<pattern>" -s done
     

4. If the active work item does not apply and the diff is not spec-only, ask whether to switch to a different work item or create a new one before committing

If no active work item exists:

• If the changes are spec-only governance maintenance, a work item is optional. Typical examples:
  • gov/** artifact files
  • rendered governance docs under docs/rfc/** or docs/adr/**
  • embedded skill or agent templates under .claude/**
  • supporting metadata such as CLAUDE.md, build.rs, or src/cmd/new.rs that only wire governance assets
• Otherwise, ask whether these changes should be attached to an existing work item or a new one
• In the standard govctl workflow, create or activate a work item before committing
• If the user explicitly says this commit is outside tracked work, record that exception in your summary

Step 4: Inspect Changes

If Jujutsu:

jj status
jj diff --stat

If Git:

git status
git diff --stat

Step 5: Compose Message

Format (mandatory):

<type>(<area>): <short summary>

<body (optional)>

Type	When to use
feat	New feature
fix	Bug fix
refactor	Code restructuring
docs	Documentation
test	Tests
chore	Maintenance

If $ARGUMENTS provided, use as basis. Otherwise derive from diff.

Step 6: Execute Commit

Jujutsu

Single-line:

jj describe -m "<type>(<area>): <summary>"
jj new

Multi-line:

jj describe --stdin <<'EOF'
<type>(<area>): <short summary>

<body>
EOF
jj new

Git

git add -A
git commit -m "<type>(<area>): <summary>"

Step 7: Post-Commit Work Item Update

After successful commit, if work item exists:

1. Add notes only when there is a closure-worthy durable constraint, retry rule, or learning to preserve after the work item is done:

   govctl work add <WI-ID> notes "Do not retry parser path X; it cannot preserve normalized arrays"
   

   Do not add notes for commands run, tests passed, review findings addressed, current plans, next actions, or temporary blockers.

2. Tick acceptance criteria (if applicable)

3. Check if work item should be marked done:

   • All criteria ticked? Suggest: govctl work move <WI-ID> done
   • Still in progress? Keep active

---

QUICK REFERENCE

# Govctl checks
govctl check                    # Validate all artifacts
govctl work list pending        # List queued and active work items
govctl work show <WI-ID>        # Show work item details
govctl work tick <WI-ID> acceptance_criteria "<pattern>" -s done

# VCS commands
jj status                       # Jujutsu
jj diff --stat
git status                      # Git
git diff --stat

---

COMMON SCENARIOS

Scenario 1: Active Work Item with Progress

1. Detect active WI-XXXX
2. govctl check → passes
3. Confirm the active WI actually matches this diff
4. If yes: ask about closure-worthy durable notes and criterion ticks
5. If no, but diff is spec-only: proceed without attaching the commit to that WI
6. If no and diff is implementation-bearing: switch/create the correct WI first
7. Commit changes
8. Ask: "Mark work item as done?" (if all criteria ticked)

Scenario 2: No Active Work Item

1. No pending work items
2. govctl check → passes
3. Check whether the diff is spec-only governance maintenance
   - If yes: proceed with a spec-only commit and mention no WI was used
   - Otherwise: ask "Which work item should this commit belong to?"
4. If implementation work applies:
   - If existing work applies: activate or use it
   - Otherwise: create WI with `govctl work new --active`
5. Commit changes

Scenario 3: Govctl Check Fails

1. govctl check → fails
2. Show diagnostics
3. Fix the issue
4. Rerun `govctl check`
5. Commit only after it passes

---

OUTPUT

Report:

1. Commit subject line
2. Work item status updates (if any)
3. govctl check result

BEGIN EXECUTION NOW.