DOX: ignore-rule changes in one VCS must be mirrored in the other
Root AGENTS.md User Preferences gains the binding agent-agnostic rule (an
agent editing .gitignore discovers it at the root without walking into
.fossil-settings/): .gitignore canonical, ignore-glob hand-derived, same work
unit, semantic differences translated per .fossil-settings/AGENTS.md. That
child doc's sync procedure is retitled from "when asked" to mandatory for
any ignore-rule change, with the one-sided-change prohibition stated.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
@ -30,7 +30,9 @@ Versioned fossil settings (one setting value or glob list per file) for this dua
- **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")
### 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.
@ -96,6 +96,7 @@ When the user requests a durable behavior change, record it here or in the relev
- cmd.exe PATH truncation (this machine, and any Windows machine with a heavily populated PATH): cmd.exe truncates a long PATH, so a tool that resolves fine in PowerShell may be "not found" when invoked via `cmd.exe /c`. Use absolute executable paths inside any `cmd /c` command line, and prefer PowerShell-native invocation unless a console host is specifically required (e.g. hidden-console test harnesses). If a tool is missing only under cmd.exe, suspect truncation before absence.
- Agent-authored text is plain ASCII by default: no em/en dashes, curly quotes, arrow or ellipsis characters, or other typographic Unicode - use ASCII equivalents (" - ", straight quotes, "->", "..."). This applies with extra force to outward-bound artifacts (ticket drafts, bug reports, emails, commit messages, anything likely to be pasted into an external system): those must be pure ASCII, verified before handover (e.g. grep for `[^\x00-\x7F]`). Legitimate exceptions: content whose subject matter is itself non-ASCII (encoding/Unicode/ANSI-art test data, or documentation demonstrating such behaviour), verbatim quotes of existing material, and cases where the user explicitly requests non-ASCII. Existing files are not to be bulk-retrofitted - the rule governs newly written text.
- Tcl has no `-e`/`-c` one-liner flag (a reflex agents carry over from perl/python/node). Stock `tclsh`/`tclsh86`/`tclsh90` recognise only `-encoding name` as a leading option; any other argument starting with `-` is NOT treated as a script file - all arguments land in `$argv` and tclsh reads commands from stdin. On a console that hangs forever at an interactive prompt; with piped/redirected stdin it exits 0 having silently ignored the supposed one-liner and executed stdin instead. (The punk kits differ: they treat `-e` as a script filename and error out immediately - no hang, but still no one-liner.) To run ad-hoc Tcl: write a temp `.tcl` file and run `tclsh path/to/file.tcl`, or pipe the script to stdin (`echo 'puts hi' | tclsh`, or a bash heredoc). Defensive habit regardless: when exec'ing tclsh non-interactively, redirect stdin (`</dev/null`, `< NUL`) so a mis-invocation exits at EOF instead of hanging.
- VCS ignore rules are dual-tracked (git + fossil). An agent that changes ignore rules in one VCS must make the equivalent change in the other in the same work unit: `.gitignore` is the canonical statement of intent and `.fossil-settings/ignore-glob` is hand-derived from it, never the reverse - so a `.gitignore` edit includes deriving the ignore-glob translation, and an ignore-glob-only edit is wrong unless it is purely catching up to `.gitignore`. Fossil globs differ semantically (no negation - tracked exceptions need explicit `fossil add`; case-sensitive; `*` crosses `/`): translate per the derivation rules in `.fossil-settings/AGENTS.md` and run its verification checks before committing.
- Throwaway fossil repositories (test/experiment repos an agent creates, e.g. in a session scratchpad) must not register in the user's real global fossil config-db: `fossil init`/`fossil open` write persistent `repo:`/`ckout:` rows into `%LOCALAPPDATA%\_fossil`, which is the enumeration source for `dev projects.work` project discovery (G-016/G-017). Set `FOSSIL_HOME` to a disposable scratch directory for the duration of such fossil commands (both fossil and `punk::repo::fossil_get_configdb` honour it first). If pollution has already occurred: `fossil all ignore <repo-path>`, delete the directory, then any `fossil all` command prunes the orphaned `ckout:` row.
- Do not commit new executable binaries (shared libs, .exe, native .so/.dll/.dylib, bare ELF/Mach-O, or zip-based .tm modules embedding executables) to the repository. Existing binaries in `bin/`, `src/vfs/`, `src/vendorlib/`, `src/vendormodules/`, and `src/bootsupport/` are there intentionally pending the build/retrieval infrastructure tracked by goals G-004/G-005/G-006; do not flag, "fix", or hassle the developer about these — they are known and will be removed once G-005 (zig build) or G-006 (pre-built download) provides an alternative. This rule stops agents from adding new binaries; it does not block the developer's interim commits of existing vendor/vfs binaries. It is workflow policy only - deliberately NOT enforced at the local VCS layer: fossil `binary-glob` is `*` (versioned in `.fossil-settings/`) so binary checkins proceed without warnings/prompts, here and in sub-projects like tomlish.
