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, .claude/settings.json (shared claude harness hooks/permissions; session-local .claude files stay ignored), 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 (mandatory for any ignore-rule change, not only on request)

Ignore-rule changes never land one-sided: any agent edit to .gitignore includes the hand-derived ignore-glob translation (plus any explicit fossil add of negation exceptions) in the same work unit, and vice versa (root AGENTS.md User Preferences carries the pointer to this rule).

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)