Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

.system/RULES.md

Raw
Rendered preview

RULES

Standards

Zero warnings, isolated evidence, reviewed output. Rigor over velocity claims.

Repository

  • Run repo commands from the dotfiles root; nested project commands run from their project root.
  • Check git status --short before edits; preserve unrelated dirty work.
  • Never run privileged, root, or elevated commands.
  • Do not delete noisy research, cache, or untracked files unless explicitly asked.
  • Prefer repo paths (pi/agent/...) over $HOME paths.

Secrets

  • .secrets is plaintext and lists repo-relative paths to encrypt; the dotfiles-aes Git filter does the encryption.
  • New secret flow:
    1. edit .secrets
    2. java bootstripper.java check
    3. git add .secrets .gitattributes
    4. git check-attr -a -- path/to/secret
  • Required attrs: filter: dotfiles-aes, text: unset, diff: unset.
  • A .secrets path must not match any ignore rule; check fails otherwise because git add -A would silently skip it.
  • Never git add -A new secret-looking files before that flow.
  • Private keys must not be staged as plaintext: git cat-file -p :path/to/key | LC_ALL=C grep -q 'BEGIN .*PRIVATE KEY' && exit 1.
  • Never print decrypted secrets; never ask for or expose DOTFILES_AES_PASSPHRASE unless I explicitly initiate setup.
  • Secret paths include ssh/*.key, gh/hosts.yml, pi/agent/auth.json, nushell/secrets.nu, app private settings.

Git

  • rebase.autostash and merge.autostash stay false; mise run check asserts it. Dirty worktree: commit first, or stash explicitly and pop it yourself.
  • The dotfiles-aes filter and pre-commit/pre-push hooks can abort Git midway; never pass --no-verify.
  • Commits and pushes require gitleaks on Git's PATH; missing Gitleaks blocks the Git operation, not the worktree.

Symlinks

  • Manifest pairs stay ordered and complete; blank line between pairs.
  • Managed symlinks never point outside HOME; no /usr, no /etc. Outside-HOME symlinks are errors: do not relink or delete them.

Repo commands

Safe checks: mise run check, mise run secrets-scan. Heavy integration: mise run ci (needs host Podman). Crypto and hooks: java bootstripper.java check | pre-commit | pre-push | install-hooks | init-crypto | setup-crypto. HOME-mutating, only on explicit request: mise run link, mise run clean. link validates manifests, converges crypto idempotently, installs or repairs hooks, and creates symlinks; restoration refuses staged changes, deletions, symlinks, changed ciphertext, or mixed states.

Nested Systems

  • quickshell/nuguland/.system/ governs the shell; its law applies there, not here.
  • Do not duplicate nested law in this System.

Docs

  • .system/ cores and specs are agent authority; read RULES and the relevant spec before governed work.
  • READMEs are human overview; agent-only knowledge belongs in .system/.
# RULES

## Standards

Zero warnings, isolated evidence, reviewed output. Rigor over velocity claims.

## Repository

- Run repo commands from the dotfiles root; nested project commands run from their project root.
- Check `git status --short` before edits; preserve unrelated dirty work.
- Never run privileged, root, or elevated commands.
- Do not delete noisy research, cache, or untracked files unless explicitly asked.
- Prefer repo paths (`pi/agent/...`) over `$HOME` paths.

## Secrets

- `.secrets` is plaintext and lists repo-relative paths to encrypt; the `dotfiles-aes` Git filter does the encryption.
- New secret flow:
  1. edit `.secrets`
  2. `java bootstripper.java check`
  3. `git add .secrets .gitattributes`
  4. `git check-attr -a -- path/to/secret`
- Required attrs: `filter: dotfiles-aes`, `text: unset`, `diff: unset`.
- A `.secrets` path must not match any ignore rule; `check` fails otherwise because `git add -A` would silently skip it.
- Never `git add -A` new secret-looking files before that flow.
- Private keys must not be staged as plaintext: `git cat-file -p :path/to/key | LC_ALL=C grep -q 'BEGIN .*PRIVATE KEY' && exit 1`.
- Never print decrypted secrets; never ask for or expose `DOTFILES_AES_PASSPHRASE` unless I explicitly initiate setup.
- Secret paths include `ssh/*.key`, `gh/hosts.yml`, `pi/agent/auth.json`, `nushell/secrets.nu`, app private settings.

## Git

- `rebase.autostash` and `merge.autostash` stay `false`; `mise run check` asserts it. Dirty worktree: commit first, or stash explicitly and pop it yourself.
- The `dotfiles-aes` filter and `pre-commit`/`pre-push` hooks can abort Git midway; never pass `--no-verify`.
- Commits and pushes require `gitleaks` on Git's `PATH`; missing Gitleaks blocks the Git operation, not the worktree.

## Symlinks

- Manifest pairs stay ordered and complete; blank line between pairs.
- Managed symlinks never point outside HOME; no `/usr`, no `/etc`. Outside-HOME symlinks are errors: do not relink or delete them.

## Repo commands

Safe checks: `mise run check`, `mise run secrets-scan`.
Heavy integration: `mise run ci` (needs host Podman).
Crypto and hooks: `java bootstripper.java check | pre-commit | pre-push | install-hooks | init-crypto | setup-crypto`.
HOME-mutating, only on explicit request: `mise run link`, `mise run clean`.
`link` validates manifests, converges crypto idempotently, installs or repairs hooks, and creates symlinks; restoration refuses staged changes, deletions, symlinks, changed ciphertext, or mixed states.

## Nested Systems

- `quickshell/nuguland/.system/` governs the shell; its law applies there, not here.
- Do not duplicate nested law in this System.

## Docs

- `.system/` cores and specs are agent authority; read RULES and the relevant spec before governed work.
- READMEs are human overview; agent-only knowledge belongs in `.system/`.