From fa483ec2e3cfa83c66c2553b714a043fec5052c5 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Wed, 5 Aug 2026 18:14:05 +1000 Subject: [PATCH] AGENTS docs: international-English idiom rule; tabled -> tabular in live agent docs Root AGENTS.md User Preferences gains the idiom discipline bullet (user, 2026-08-05): agent-authored prose avoids idioms whose meaning differs or reverses across English variants (to table, momentarily, presently, moot, punt, luck out, out of pocket, bi-weekly, fortnight, knock back, on the nose, quite ); table-formatted punk::args output is written 'tabular usage'/'tabular help', never 'tabled'. Established technical slang (dogfooding, spike testing) stays fine. Applied to the seven live agent-doc instances: ARCHITECTURE.md, bin/AGENTS.md, src/AGENTS.md, src/bootsupport/AGENTS.md (x2), src/vfs/AGENTS.md (x2); architecture_lint clean. Deliberately unchanged: archived goal records (historical wording), goals/G-168 Acceptance (contract prose - separate approval), and code-tier comments/strings plus their synced copies (undecided). Claude-Session: https://claude.ai/code/session_01TNn3C58Cpekt3CsZNLCqvR Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- AGENTS.md | 1 + ARCHITECTURE.md | 2 +- bin/AGENTS.md | 2 +- src/AGENTS.md | 2 +- src/bootsupport/AGENTS.md | 2 +- src/vfs/AGENTS.md | 2 +- 6 files changed, 6 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6679ce4d..8ab35ecf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,6 +105,7 @@ When the user requests a durable behavior change, record it here or in the relev - 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. - 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. +- International English idiom discipline (user, 2026-08-05): agent-authored prose must avoid idioms whose meaning differs or reverses across English variants (US vs UK/AU). Known traps: 'to table' something (US: postpone; UK/AU: put forward) - for table-formatted punk::args output write 'tabular usage'/'tabular help', never 'tabled' (legacy 'tabled' survives in code comments/strings and archived goal records); 'momentarily' (US: soon; UK/AU: for a moment); 'presently' (currently vs soon); 'moot' (US: irrelevant; UK/AU: debatable); 'punt' (US: defer/give up; AU: have a go/gamble); 'luck out' (US: got lucky; elsewhere often read as ran out of luck); 'out of pocket' (US slang: unreachable; elsewhere: paying one's own costs); 'bi-weekly'/'bi-monthly' (ambiguous everywhere - state the period explicitly); 'fortnight' (unfamiliar to many US readers); 'knock back' (AU: reject); 'on the nose' (US: exactly right; AU: smells off/suspect); 'quite ' (UK: mild downgrade; US: intensifier). Widely adopted technical slang (dogfooding, spike testing, smoke test) is fine. When unsure, prefer plain literal phrasing. ## Commit Conventions (any VCS) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index aecda6eb..02ea965b 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -42,7 +42,7 @@ app package from src/lib/ (app-punkshell, app-punkscript, app-repl, app-shellsp ## Boot and launch chain - **Kit anatomy.** Each `src/vfs/*.vfs` folder is a runtime payload; `src/runtime/mapvfs.toml` (G-024, tomlish-parsed; deprecated `mapvfs.config` line format still readable) maps payload folders to platform runtimes under `bin/runtime//` as named kit outputs, with named groups and generative version-named schemes; an optional sibling `src/vfs/.vfs.toml` declares payload packages materialized INTO the folder with drop-in-wins precedence (G-115 - spec: `src/vfs/README.md`); `src/vfs/_vfscommon.vfs/` is a generated merge of common libraries (never hand-edited); `src/vfs/_config/` holds the entry scripts. Sources: `src/vfs/AGENTS.md`, `src/runtime/AGENTS.md`. -- **Entry point.** `src/vfs/_config/punk_main.tcl` (thin main sourcing the shared boot core - G-031). An optional first argument is a dash-delimited package mode composed of tokens from `minted`, `os`, `src`, `internal` (`internal` is always appended when absent; `minted` was named `dev` pre-0.43.0), optionally scoped with the `proj:` prefix (G-033: `minted`/`src` resolve against the project containing the cwd - walk-up to the nearest git/fossil repo root with a punkshell-style src tree - instead of the executable's own project; discovery is always reported, never a silent rebind). The next argument is the subcommand: `shell`, `script`, `punk`, `tclsh`, `shellspy`, `buildinfo`, `help`. A non-subcommand first argument naming an existing file (or `lib:*` reference) is treated as a script invocation; a first argument of exactly `-e` runs the following argument as a Tcl one-liner (G-077, achieved - handled as `script -e`; tool-style kits keep `-e` routed to their own processor); anything else is refused with usage (G-032); no arguments at all means interactive shell. Subcommands map to app packages under `src/lib/` (`app-punkshell`, `app-punkscript`, `app-repl`, `app-shellspy`). The launch surface self-documents through punk::args (G-032; single-mechanism revision 2026-08-05 in boot core 0.5.0): `help ?subcommand? ?arg ...?` - the only help entry, trailing words accepted so `help` can be prepended to a command line - renders tabled usage from the moduledoc definitions plus project registrations (`::punkboot::project_subcommand_info` - summaries, definition ids, optional declared parse), degrading to a plain subcommand list when that stack is unavailable; help FLAGS are never intercepted (a leading `-help` earns the refusal, ` -help` belongs to the subcommand). Source: `src/vfs/AGENTS.md`. +- **Entry point.** `src/vfs/_config/punk_main.tcl` (thin main sourcing the shared boot core - G-031). An optional first argument is a dash-delimited package mode composed of tokens from `minted`, `os`, `src`, `internal` (`internal` is always appended when absent; `minted` was named `dev` pre-0.43.0), optionally scoped with the `proj:` prefix (G-033: `minted`/`src` resolve against the project containing the cwd - walk-up to the nearest git/fossil repo root with a punkshell-style src tree - instead of the executable's own project; discovery is always reported, never a silent rebind). The next argument is the subcommand: `shell`, `script`, `punk`, `tclsh`, `shellspy`, `buildinfo`, `help`. A non-subcommand first argument naming an existing file (or `lib:*` reference) is treated as a script invocation; a first argument of exactly `-e` runs the following argument as a Tcl one-liner (G-077, achieved - handled as `script -e`; tool-style kits keep `-e` routed to their own processor); anything else is refused with usage (G-032); no arguments at all means interactive shell. Subcommands map to app packages under `src/lib/` (`app-punkshell`, `app-punkscript`, `app-repl`, `app-shellspy`). The launch surface self-documents through punk::args (G-032; single-mechanism revision 2026-08-05 in boot core 0.5.0): `help ?subcommand? ?arg ...?` - the only help entry, trailing words accepted so `help` can be prepended to a command line - renders tabular usage from the moduledoc definitions plus project registrations (`::punkboot::project_subcommand_info` - summaries, definition ids, optional declared parse), degrading to a plain subcommand list when that stack is unavailable; help FLAGS are never intercepted (a leading `-help` earns the refusal, ` -help` belongs to the subcommand). Source: `src/vfs/AGENTS.md`. - **Package modes pick module provenance.** `internal` uses module snapshots baked into the kit at bake time; `minted` loads the mint output trees at repo-root `modules/` and `lib/`; `src` loads the unbuilt working tree (`src/modules`, `src/lib`, `src/bootsupport`, `src/vendormodules`) with `package prefer latest` so magic-version dev modules (`999999.0a1.0`) beat stamped snapshots. `src` mode is the standard way to verify working-tree changes without a rebuild. Source: `bin/AGENTS.md` "Launch package modes". - **Payload mount derivation (G-129, achieved).** The boot keys zipfs presence on `tcl::zipfs::mount` and derives where the executable's attached archive actually mounted from the mount table itself (the entry whose archive file is the executable; fallback: the mount containing the boot script) instead of assuming `tcl::zipfs::root` + `//zipfs:/app`. Modern runtimes still answer `//zipfs:/app`; the androwish/undroidwish 8.6 backport has no `root` command, mounts at the executable's own path, and boots the same payload through its `app/main.tcl` in-archive hook (`src/vfs/punk8win.vfs` carries fauxlinks for both conventions). A mounted archive the boot cannot attribute is reported on stderr rather than silently yielding no internal paths. The derivation procs stay defined post-boot (`::punkboot::zipfs_kit_mountbase`). Sources: `src/vfs/AGENTS.md`, `bin/AGENTS.md` "Kit-wrappable runtime requirements", `src/tests/shell/testsuites/punkexe/kitmountpoint.test`. - **Static package capture (G-058, achieved).** Boot probe-loads the runtime's statically linked packages in a throwaway interp and records what each provides; every interp the shell fabricates (boot, codethread, shellthread workers) seeds `package ifneeded {load {} }` from that record, and `punk::packagepreference` resolves static-vs-bundled version-aware. Sources: `src/vfs/AGENTS.md`, `goals/archive/G-058-static-runtime-packages.md`. diff --git a/bin/AGENTS.md b/bin/AGENTS.md index 11eed0fc..7a0dea77 100644 --- a/bin/AGENTS.md +++ b/bin/AGENTS.md @@ -97,7 +97,7 @@ platform-specific difference left in examples is path separator style ### Launch package modes (built punk shells) -The first argument to a built punk shell may be a dash-delimited package mode composed of tokens from `minted`, `os`, `src`, `internal` (e.g. `punksys src`, `punk902z minted-os`), optionally scoped with the `proj:` prefix (e.g. `punk91 proj:internal-src`). (`minted` was named `dev` before punkshell 0.43.0 - clean rename, no alias: old kits accept only `dev`, current kits only `minted`.) `internal` is the default and is always appended when absent. A first argument that is not a valid mode list is treated as a subcommand instead (a `proj:` prefix on a non-mode string is not consumed either). Implementation: `src/vfs/_config/punk_main.tcl` (search `all_package_modes`). The full packagemode contract (block meanings, ordering, proj: examples) is the punk::args documentation at id `(script)::punkexe` (module `punk::args::moduledoc::punkexe`), and the launch surface is self-documenting in every current kit (G-032; single-mechanism revision 2026-08-05): ` help ?subcommand? ?arg ...?` renders tabled usage (with the packagemode contract as the leader row; trailing words after the subject are accepted and ignored, so `help` can be prepended to an existing command line) - degrading to a plain subcommand list where the punk::args stack is unavailable. Help FLAGS are never intercepted: `-help` after a subcommand is that subcommand's own argument, and a leading `-help` falls under the refusal below. An unknown first argument that names no existing file (and no `lib:*` scriptlib reference) is refused with that usage rather than silently attempted as a script. A first argument of exactly `-e` instead runs the following argument as a Tcl one-liner (G-077; equivalently ` script -e