diff --git a/AGENTS.md b/AGENTS.md index 71890eec..8b954c91 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -86,6 +86,7 @@ When the user requests a durable behavior change, record it here or in the relev - LF line endings are strongly preferred for all files in this repository. Converting a CRLF text file to LF when an edit touches it is correct and welcome - do not preserve CRLF for diff-minimisation. Preserve existing line endings only for files with deliberately mixed/CRLF endings (e.g. line-ending round-trip test data) or when explicitly instructed for a file. - If the active editor is on a source-derived snapshot, bootstrap copy, or build output path such as `src/bootsupport/`, root `modules/`, root `lib/`, `modules_tcl8/`, `modules_tcl9/`, `lib_tcl8/`, or `lib_tcl9/`, confirm the intended target before editing unless the user explicitly named that path. - 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. +- 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 `, 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. ## Commit Conventions (any VCS) diff --git a/goals/G-016-projects-work-git-discovery.md b/goals/G-016-projects-work-git-discovery.md index 73677f45..6c717825 100644 --- a/goals/G-016-projects-work-git-discovery.md +++ b/goals/G-016-projects-work-git-discovery.md @@ -71,6 +71,18 @@ Result-shape considerations: ## Notes +- Staleness of the fossil config-db source itself (observed 2026-07-11): a + throwaway test repo fossil-init/opened in an agent session scratchpad (temp + path) persisted for days as row 1 of the listing - `repo:` rows live until an + explicit `fossil all ignore`, and `ckout:` rows are pruned only by `fossil all` + commands run after the checkout dir is deleted. So the "registry can go stale" + concern listed against the punk-maintained-registry option applies equally to + fossil's own central config-db. Whatever enumeration design this goal ships + needs a staleness story for BOTH VCS sources - e.g. flag or filter rows whose + checkout dirs are missing or under known temp locations - especially for the + `-return dict|json` machine forms agents will consume unfiltered. The + prevention side (scratch `FOSSIL_HOME` for throwaway repos) is recorded in + root AGENTS.md User Preferences. - Depends on nothing, but its value to agents is realised through G-015 (reliable piped invocation) and G-017 (agent guidance documenting the call). - The `-cd` / `-detail` options and case-insensitive glob behaviour of the