Skip to content

feat(init): establish Git Intent and the operation contract #1

Description

@uklok-agent

Motivation

Git exposes excellent low-level primitives, but many common maintenance tasks
still require humans and coding agents to assemble fragile command sequences.

The desired outcome is often simple; the implementation is not.

Git Intent should capture those operations once as deterministic,
recovery-aware tools reusable by developers, automation systems, and agent
ecosystems.

Project thesis

Express the Git intent, not the surgery.

An operation belongs in Git Intent when:

  1. its intent is common;
  2. its raw Git implementation is non-trivial or risky; and
  3. it can be given explicit safety and recovery semantics.

Git Intent should build on mature Git tooling rather than reproduce it merely
for ownership.

Initial reference operation

Introduce git-fix-author, based on an author-history repair workflow that has
already exposed real failure modes around pagers, committer identity, merge
topology, empty commits, ref movement, and recovery.

The operation rewrites author and committer attribution across an inclusive
commit range while preserving its documented history invariants and creating a
native Git recovery ref before mutation.

Git discovers the installed git-fix-author executable as:

git fix-author

Operation lifecycle

The first implementation establishes the repository-wide lifecycle:

  1. preflight;
  2. resolve;
  3. preview;
  4. checkpoint;
  5. execute;
  6. verify; and
  7. recovery and publishing guidance.

Agent integration

Package the operation as an Agent Skill with:

  • precise trigger metadata;
  • explicit exclusion cases;
  • the canonical executable;
  • a focused Git-semantics reference; and
  • a dry-run-first workflow.

The skill should select and invoke a reviewed operation rather than teach an
agent to improvise equivalent history surgery.

The agent chooses the operation. The operation owns the surgery.

Deliverables

  • Project README and public positioning
  • MIT license
  • Project philosophy
  • Operation contract
  • Architecture documentation
  • Contribution guidelines
  • Security policy
  • Code of conduct
  • Agent Skills-compatible git-fix-author
  • Human-facing operation documentation
  • Tested executable with dry-run and non-interactive modes
  • Explicit author and committer behavior
  • Recovery refs and bounded local-ref updates
  • Automated invariant and rejection tests
  • Skill validation
  • Linux and macOS CI
  • Community issue forms
  • Follow-up backup lifecycle issue

Required git-fix-author invariants

  • Dirty worktrees/indexes are rejected.
  • Invalid and non-ancestor ranges are rejected before mutation.
  • Dry runs create no objects or refs and change no configuration or files.
  • File trees and commit messages remain identical.
  • Author and committer timestamps remain identical.
  • Empty commits and merge topology remain intact.
  • The requested author is applied to the full resolved range.
  • The committer defaults to the author unless separately specified.
  • Git identity configuration is never modified.
  • The original finish tip remains reachable under
    refs/backup/author-rewrite-* unless --no-backup is explicit.
  • Related local branch tips are previewed and updated atomically by default.
  • Tags and remote-tracking refs are not changed.
  • No remote publication or force-push occurs.

Non-goals

  • Replacing Git or creating another VCS
  • Wrapping ordinary Git commands
  • Building a generic Git agent or prompt pack
  • Building a skills marketplace
  • Building a plugin or engine-adapter framework before real operations require
    one
  • Implementing backup lifecycle management inside the initial rewrite path

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions