harn

Harn

Harn is a repo-native guardrail for agentic coding.

Use Harn to ensure code changes match a predeclared assumption-impact plan.

Harn is not a work log. Harn is a pre-change contract between intended assumption impact and the actual Git diff.

Source of truth:

.harn/assumptions/ = current assumption truth
.harn/plans/       = proposed and applied assumption transitions
source anchors     = code locations tied to assumptions
git diff           = what actually changed

Required Workflow

Before starting, check Git baseline:

git status --short
git rev-parse --is-inside-work-tree

If the repo is not a Git repo, initialize Git and create a baseline commit before Harn planning unless the human explicitly says this is a bootstrap/baseline operation.

If there is large uncommitted scaffold work, stop and ask whether to commit it first. Do not use a dirty lock to explain already-written work unless the human explicitly accepts that risk.

1. Explore existing assumptions.

   • Run harn find.
   • Use harn find --file <path> before editing relevant files.
   • Use harn find <assumption-id> for assumption details.
   • Use harn find --depended-by <id> --depth <n> to inspect dependent assumptions.

2. Draft or update a plan in .harn/plans/.

   • Declare intended assumption changes.
   • Account for affected anchors.
   • Use only the valid enum values listed below.

3. Check the plan.

   • Run harn plan check <plan-id>.
   • Fix every blocking item before locking.

4. Lock the plan.

   • Run harn plan lock <plan-id>.
   • Only one plan may be locked in a worktree at a time.
   • Do not implement before the plan is locked unless explicitly asked.
   • If the lock says dirty_at_lock: true, report this to the human before continuing.

5. Implement the code change.

   • Keep edits within the locked plan.
   • During implementation, use harn find --changed, harn find --staged, and harn find --plan <plan-id> to verify scope.