Air traffic control for AI coding

nool propose

nool propose creates a candidate transition that can be inspected before solidification. It is where intent and implementation become reviewable.

  • Declare the user-visible or architectural intent.
  • Add justification when blast radius expands.
  • Inspect the candidate before solidifying high-risk changes.
nool propose --path src/config/billing.ts --path src/pages/Pricing.tsx --intent "Add Stripe checkout flow without changing licensing enforcement"

Concrete workflow

Run propose after implementation and before solidification. Name the files you changed with `--path`: other agents may have uncommitted work in the same tree, and `--all` would sweep it into your knot. The command below gives the change a tight business intent that explicitly excludes licensing enforcement.

nool propose --path src/config/billing.ts --path src/pages/Pricing.tsx --intent "Add Stripe checkout flow without changing licensing enforcement"

When to use --fast

Full mode is the default. `--fast` is an explicit, unsafe opt-in for bounded content, UI or docs changes: it lands in seconds and defers semantic validation, which you settle later with `nool validate --all`. `nool doctor --strict` counts unsettled fast knots against release readiness.

  • The task is already implemented and scoped.
  • The changed paths are expected.
  • You need an agent-readable candidate quickly before final checks.
nool propose --path docs/faq.md --intent "Clarify refund FAQ" --fast
nool validate --all

When full mode matters most

Full mode runs the ghost run (the build and the affected tests in a private worktree) before the change can land. Keep it for release preparation, security-sensitive changes, policy changes, schema migrations and multi-agent merges. `--justification` explains a change whose blast radius goes past its declared scope.

nool propose --path policies/billing.yaml --intent "Rotate billing policy without weakening license checks" --justification "Touches payment policy and licensing boundaries"

Land part of a file

`--hunks <file>#<start>-<end>` lands only the diff hunks wholly inside that working-tree line range; the file's other hunks, such as another session's uncommitted edit, stay in the working tree. The ghost run checks exactly the content that lands. A range that cuts through a hunk is refused with the file's hunk list.

nool propose --hunks src/api/limits.ts#40-88 --intent "Add rate limiting"

Configuration changes land alone

A change to `nool.toml` or `workspace.toml` changes the rules every later seal runs under, so it must be its own knot with a justification typed for it. Propose and solidify refuse (`CONFIG_CHANGE`) a knot that mixes a configuration file with any other file, or that has no justification. The one exception is a policy pin, which lands with the policy files it names.

nool propose --path nool.toml --kind config --justification "Raise the blast threshold for the monorepo split" --solidify

What to do before solidify

Treat propose as the review packet, not the final commit. Read the changed path list, run tests, compute blast radius for risky files, and only then seal the candidate.

nool debug blast-radius src/config/billing.ts src/pages/Pricing.tsx --compact