Dual-VCS docs: 'fossil extras' drift note in AGENTS infrastructure
Root AGENTS.md dual-VCS bullet and .fossil-settings/AGENTS.md Work Guidance
now state that 'fossil changes' never lists untracked files, so a git-added
file missed by its mirrored checkin surfaces only in 'fossil extras' (normally
empty in this tree) - glance at it before finishing a dual-VCS work unit, and
use the tracked-set comparison in .fossil-settings Verification for
accumulated drift. Motivating instance fixed in the immediately preceding
fossil catch-up checkin (2 .test files git-added in the G-123/G-127
increments, never fossil-added).
Assisted-by: harness=opencode; primary-model=opencode/kimi-k3; api-location=unknown
@ -44,11 +44,12 @@ Ignore-rule changes never land one-sided: any agent edit to `.gitignore` include
## Work Guidance
- Commit cadence for this dual-VCS tree (agents commit each change-set to both git and fossil in the same work unit; catch-up checkins when fossil has lagged behind developer git commits) is governed by root `AGENTS.md` User Preferences.
- Drift detection: `fossil changes` is blind to untracked files - a new file git-added without the mirrored `fossil add` surfaces only in `fossil extras`, which is normally empty in this tree (every path is either fossil-tracked or covered by ignore-glob). Check `fossil extras` before any fossil checkin and treat entries as drift to disposition; when a mirrored checkin ADDED files in git, confirm the same paths land in the fossil checkin's file list. The Verification comparison below catches accumulated drift - run it when extras shows anything and after multi-commit catch-ups.
- `git ls-files | sort` vs `(fossil ls; fossil extras) | sort` → differences limited to the documented exception set + fossil-generated manifests
- `git ls-files | sort` vs `(fossil ls; fossil extras) | sort` → differences limited to the documented exception set + fossil-generated manifests (this is the check that catches git-tracked files fossil never added - they appear in the fossil-extras half)
@ -100,7 +100,7 @@ When the user requests a durable behavior change, record it here or in the relev
- 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.
- For ad-hoc punkshell scripts that need working-tree modules, use `bin/punk91 src script` for stdin scripts or `bin/punk91 src script path/to/file.tcl` for script files. Do not use `bin/punk91 src` for piped/redirected snippets: `src` alone starts the live shell on the repo source tree and may execute stdin input but then remain in shell/eof handling instead of exiting cleanly. Keep `src` before `script` so the working-tree modules are loaded.
- 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.
- Dual-VCS commit cadence (user, 2026-07-29): in a tree tracked by both git and fossil (this repo; git is primary), agents commit each change-set to BOTH VCS in the same work unit by default - a request to commit means both, and only an explicit single-VCS instruction narrows it. The fossil checkin mirrors the git commit (same message body; new/renamed files need explicit `fossil add` / `fossil mv`). Before the fossil checkin, run `fossil changes` and look for pending material beyond the current change-set: the developer may commit to git manually and let fossil lag, and a plain `fossil commit` sweeps everything pending - when lag is present, either land a separate catch-up checkin first, or fold the lag in with a message naming the covered git commits (per-change rationale stays in git history; the catch-up message summarizes). Coexistence mechanics (ignore sync, CRLF prompt avoidance, tracked-set verification) are in `.fossil-settings/AGENTS.md`.
- Dual-VCS commit cadence (user, 2026-07-29): in a tree tracked by both git and fossil (this repo; git is primary), agents commit each change-set to BOTH VCS in the same work unit by default - a request to commit means both, and only an explicit single-VCS instruction narrows it. The fossil checkin mirrors the git commit (same message body; new/renamed files need explicit `fossil add` / `fossil mv`). `fossil changes` never lists untracked files: a new file git-added but missed by its mirrored checkin is invisible there and surfaces only in `fossil extras`, which is normally empty in this tree - glance at it before finishing a dual-VCS work unit and treat any entry as drift to disposition (drift instance 2026-08-01: two .test files git-added in the G-123/G-127 increments, never fossil-added). Before the fossil checkin, run `fossil changes` and look for pending material beyond the current change-set: the developer may commit to git manually and let fossil lag, and a plain `fossil commit` sweeps everything pending - when lag is present, either land a separate catch-up checkin first, or fold the lag in with a message naming the covered git commits (per-change rationale stays in git history; the catch-up message summarizes). Coexistence mechanics (ignore sync, CRLF prompt avoidance, tracked-set verification) are in `.fossil-settings/AGENTS.md`.
- 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.
- Fossil checkout branch discipline: in fossil, `tip` means the newest check-in on ANY branch - not the trunk tip. A `fossil open ... tip` or `fossil update tip` run shortly after an upstream feature-branch commit silently parks the checkout on that branch, and every later plain `fossil update` keeps following it. When opening or refreshing any fossil checkout (including reference checkouts such as `TEMP_REFERENCE/tcl9`), name the branch explicitly (`fossil update trunk`), never `tip`, and confirm the `tags:` line of `fossil status` shows the intended branch afterwards.
- 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.
