dual-VCS coexistence contract: untrack fossil-generated manifests, add .fossil-settings/AGENTS.md

git tracked fossil's generated checkout artifacts (manifest, manifest.tags,
manifest.uuid - regenerated on every fossil checkin/checkout per the
versioned 'manifest' setting value 'rut'), which would churn as soon as
fossil commits begin. They are now untracked and git-ignored with
root-anchored patterns (nested manifest-named files elsewhere are real
content and stay tracked). Fossil control files (.fslckout/_FOSSIL_/
*.fossil) were already correctly git-ignored, and .fossil-settings/
.fossil-custom correctly git-tracked.

New .fossil-settings/AGENTS.md is the canonical home of the git+fossil
contract: which files each system must not track, the ignore-glob
derivation rules (no negation -> wholesale-ignore + explicit fossil add of
tracked exceptions; directory pruning; * crossing /; */ variants for
match-anywhere patterns; default dotfile skipping), and the verification
procedure any future "sync the ignores" request must follow (fossil extras
against git check-ignore, and a tracked-set comparison bounded to the
documented exceptions). The ignore-glob header now points there instead of
duplicating the rules; root AGENTS.md Child DOX Index gains the entry.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

.fossil-settings/AGENTS.md

@@ -0,0 +1,44 @@
+# .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
+
+### 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.
+
+### 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)

.fossil-settings/ignore-glob

@@ -1,10 +1,7 @@
 #Derived from .gitignore (the canonical statement of ignore intent) - keep in sync manually.
-#Fossil glob semantics differ from git (verified fossil 2.28):
-# - no negation patterns: the tracked exceptions under bin/ (AGENTS.md, *.cmd, *.kit, *.tcl,
-#   *.sh, *.bash) cannot be expressed - bin/* is ignored wholesale and source-controlled bin
-#   items must be explicitly 'fossil add'ed (ignore-glob does not affect already-managed files)
-# - a bare directory name prunes the whole tree; * crosses directory separators
-# - git patterns intended to match at any depth need an additional */ variant here
+#See .fossil-settings/AGENTS.md for the git+fossil coexistence contract: the glob semantic
+#translation rules (fossil has no negation - bin/* is wholesale-ignored with the tracked
+#exceptions handled by explicit 'fossil add'), and the verification procedure for syncing.
 .git
 CVS
 

.gitignore

@@ -64,6 +64,14 @@ _FOSSIL_
 .fslckout
 *.fossil
 
+#fossil-generated checkout artifacts - regenerated on every fossil checkin/checkout per the
+#versioned 'manifest' setting (value 'rut'); fossil auto-manages them and they must not be
+#git-tracked. Anchored: nested manifest-named files elsewhere are real content.
+#See .fossil-settings/AGENTS.md for the git+fossil coexistence contract.
+/manifest
+/manifest.uuid
+/manifest.tags
+
 #miscellaneous editor files etc 
 *.swp
 *.log

AGENTS.md

@@ -138,6 +138,7 @@ When the user requests a durable behavior change, record it here or in the relev
   - `src/doc/` — Generated documentation (see src/doc/AGENTS.md)
   - `src/testansi/` — Sample ANSI art files (do not modify)
 - `bin/` — Built punk shell executables, launch package modes (incl. `src` mode for working-tree verification), plain runtime kits (see bin/AGENTS.md)
+- `.fossil-settings/` — Versioned fossil settings and the git+fossil dual-VCS coexistence contract: ignore-sync rules, files neither system may track (see .fossil-settings/AGENTS.md)
 - `GOALS.md` — Top-level technical goal index; required read for non-trivial work (no child AGENTS.md; the file documents its own format and the agent goal-authoring workflow)
 - `GOALS-archive.md` — One-line records of achieved goals moved out of the active index (historical context only)
 - `goals/` — Optional detail prose for goals needing more than a one-line summary (see goals/AGENTS.md)

manifest

@@ -1,8 +0,0 @@
-C initial\sempty\scheck-in
-D 2025-09-27T18:28:21.559
-R d41d8cd98f00b204e9800998ecf8427e
-T *branch * trunk
-T *sym-trunk *
-U jnoble
-Z 3f45351c1dc810e1e3525545cb4124cd
-# Remove this line to create a well-formed Fossil manifest.

manifest.tags

@@ -1,2 +0,0 @@
-branch trunk
-tag trunk

manifest.uuid

@@ -1 +0,0 @@
-8617f402ca78b8a1ae3566af83ccb97bec705e0b273c1ec5e76e8c6aa276a182