NAME

scope-demo - show --commit-scope resolution

SYNOPSIS

scope-demo

[--commit-scope]=[value]

DESCRIPTION

scope-demo exercises --commit-scope resolution, the rule that binds every audit row to a specific git toplevel. The trailer-emitting hook later filters audit rows by this exact-match field, so a stable resolution policy is the load-bearing part of the audit contract.

Three resolution modes:

- "auto" (the default): resolve to the git toplevel of cwd. If
  cwd is not inside a git repo, "auto" is a hard error. Kai
  typically works in the directory above her repos, so this is
  the common case.
- "<absolute-path>": use that path as the scope. Validated as
  a real git checkout at resolution time. Required when cwd is
  outside any git repo or when the operator wants to bind the
  audit row to a different repo than cwd belongs to.
- $COILY_COMMIT_SCOPE: if the flag value is the default ("auto")
  and the env var is set, the env var wins. Lets long-running
  shells bind to one scope per session without typing the flag
  every call.

There is no opt-out. Every audit row from a non-SkipScope verb must bind to a real commit. Dashes, "none", "off", or any other "skip" sentinel is rejected at resolution. Verbs that genuinely should not tie to a repo set verb.Spec.SkipScope = true at the definition site so the decision is visible in the verb's source, not papered over at the call site.

Why the strictness:

- An audit row whose scope cannot be reconstructed from git
  history is dead weight forensically. The whole point of the
  log is that "what code ran" is answerable from the row plus
  git history.
- Allowing "skip" at the call site means a hostile caller can
  hide. The audit log's truthfulness is the contract.

Operating model for an agent setting --commit-scope:

- Prefer "auto". Reach for an explicit path only when the call
  site is genuinely outside a repo (running from $HOME, /tmp).
- Do NOT set $COILY_COMMIT_SCOPE to a sentinel value to escape
  the gate. The env var is checked for repo validity.
- On "scope: cwd is not inside a git repo" failure: cd into a
  repo, pass an explicit path, or recognize that the call is in
  fact uncopied to any repo and surface that to the operator.

Usage:

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

GLOBAL OPTIONS

--commit-scope="": bind audit rows to a commit scope (auto resolves to git toplevel of cwd) (default: "auto")

COMMANDS

where