punkshell/.fossil-settings/AGENTS.md

.fossil-settings/

Purpose

Versioned fossil settings (one setting value or glob list per file) for this dual-VCS tree: git and fossil both track the same project. This file is also the canonical home of the git+fossil coexistence contract, including the rules for keeping .gitignore and ignore-glob in sync.

Ownership

• .gitignore is the canonical statement of ignore intent; ignore-glob is hand-derived from it per the rules below - never the other direction.
• .fossil-settings/ and .fossil-custom/ are git-tracked (versioned fossil config rides in git even at sites where fossil is unused).

Local Contracts

Commit warning suppression

• binary-glob is *: binary checkins are allowed by default with no fossil warnings/prompts (applies to punkshell and is the pattern for sub-projects like tomlish). The aim of an eventually binary-free tree (goals G-004/G-005/G-006) is agent/workflow policy (see root AGENTS.md User Preferences) and is deliberately NOT enforced at the local VCS layer.

Files each system must not track

• Fossil-generated checkout artifacts: the manifest setting (value rut) makes fossil regenerate manifest, manifest.uuid and manifest.tags at the checkout root on every checkin/checkout. Fossil auto-manages them (they never appear in extras and cannot be added). Git must ignore them - root-anchored /manifest, /manifest.uuid, /manifest.tags in .gitignore (anchored because nested manifest-named files elsewhere are real content) - and must never track them.
• Fossil control files: .fslckout / _FOSSIL_ (checkout db), *.fossil (repository db) - git-ignored; fossil auto-ignores its own.
• Git control tree: .git stays in ignore-glob. Fossil skips dot-prefixed names by default, but an addremove --dotfiles scan would otherwise descend into it.
• Git meta files that are project content (.gitignore, .gitkeep placeholders) ARE fossil-tracked for mirror completeness - capture them with --dotfiles on addremove/add scans.

ignore-glob derivation rules (verified against fossil 2.28)

• No negation exists in fossil globs. Git's /bin/* + !exception pattern becomes: ignore bin/* wholesale and explicitly fossil add the tracked exceptions (ignore-glob never affects already-managed files, so they stay tracked). The exception set is whatever git tracks under an ignored tree - at the time of writing: bin/AGENTS.md, bin/*.cmd, bin/*.kit, bin/*.tcl, bin/*.sh, bin/*.bash, plus force-tracked one-offs (bin/libssp-0.dll, src/vfs/punk9magicsplat.vfs/lib/nmake/x86_64-w64-mingw32-nmakehlp.exe). Derive the current set with the verification comparison below rather than trusting this list.
• A bare directory name prunes that whole tree; * crosses /; git patterns intended to match at any depth need an additional */ variant; # comment lines are honoured.
• Do not add the fossil-generated names (manifest, manifest.uuid, manifest.tags) to ignore-glob - fossil handles them itself.
• Nested .gitignore files are git-only: ignore files inside subtrees (e.g. the project-layout templates under src/project_layouts/) are honoured by git as nested ignores of the outer repo but invisible to fossil - template content they match is untracked in git yet managed by fossil. Treat such divergence as a signal to review the git side (usually git add -f of the affected template files).
• Case sensitivity differs: git ignore matching is case-insensitive on Windows (core.ignorecase), fossil glob matching is case-sensitive - e.g. a todo.txt pattern hits vendored TODO.txt in git but not fossil.

Safe sync procedure (when asked to "sync the ignores")

1. Edit .gitignore first (canonical), then hand-translate to ignore-glob using the rules above. Never translate a negation literally.
2. Verify from the checkout root:
   • fossil extras | git check-ignore --stdin must output nothing (fossil is not under-ignoring relative to git).
   • Git-tracked files invisible to fossil must reduce to the documented exception set plus the fossil-generated manifests: compare git ls-files | sort against (fossil ls; fossil extras) | sort (beware false diffs from case and non-ASCII path encoding).
3. A fossil addremove after a glob change should use --dotfiles and be reviewed before commit; pending adds captured under older globs are stale - fossil revert cancels uncommitted adds without touching file content when nothing is committed on top of them.

Work Guidance

Verification

• fossil extras | git check-ignore --stdin → empty
• git ls-files | sort vs (fossil ls; fossil extras) | sort → differences limited to the documented exception set + fossil-generated manifests

Child DOX Index

(none)