NAME

gittree-demo - show the clean+synced gate

SYNOPSIS

gittree-demo

DESCRIPTION

gittree-demo exercises the clean+synced gate that fronts every .coily/coily.yaml repo verb. The gate refuses a repo-verb invocation whenever the working tree could not be reconstructed from git history alone:

- uncommitted changes (modified files)
- untracked files (new files not in .gitignore)
- detached HEAD (no branch context for the commit)
- a branch without a configured upstream
- upstream that has not been fetched recently

Why: every repo-verb audit row points at a commit. If the tree was dirty at the time of invocation, the audit row alone cannot tell you what code ran. Refusing the verb keeps the audit log forensically reconstructable from git history later.

Scope of the gate:

- Repo verbs only. Built-in coily verbs (lockdown, setup, audit
  inspection) are reproducible from the binary version trailer
  in the audit row and are not gated.
- The gate is run per call. A repo can be clean at call N and
  dirty at call N+1.
- There is no global "skip" knob. --audit-override-dirty exists
  for genuine emergencies; it tags the audit row with
  audit_override=true and captures the working tree status so
  the run can still be reconstructed after the fact.

Operating model for an agent calling repo verbs:

- On refusal, the State.Recovery field names the dictatable shell
  command the operator should run (git status, git commit, git
  push, edit .gitignore). The agent should surface that recovery
  hint verbatim, not invent its own.
- Do NOT auto-stash or auto-commit to clear the gate. That
  destroys the very signal the gate was protecting (what was the
  working tree at audit time).
- The gate runs git plumbing under the hood. If git itself is
  broken (not installed, .git corrupted), the gate fails with a
  structured error rather than silently passing.

Usage:

gittree-demo [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]

COMMANDS

build

pretend-build verb, gated on a clean tree