IF Commons GitHub

Ergonex host: typed templates, generated files and what is managed

0003Active

0003-host · owner if · domain commons

Source state and target state

FR-001checkpassing

The source state MUST be the typed manifest <home>/.ergonex/workspace.ts (repositories, tool catalog, policy and the data the templates read, such as the Git identity and the groups of repositories), read once at the boundary by the kernel's decoder, and a manifest that does not decode MUST be reported as ergonex:Error findings naming each field and MUST stop the run before anything is changed.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: the manifest is loaded from workspace.ts and decoded once, and one that does not decode is reported as ergonex:Error findings naming each field and stops the run before anything is changed (ergonex-manifest.test.ts proves the decoder)

Proved by: ergonex/suite/ergonex-command.test.ts, ergonex/suite/ergonex-manifest.test.ts

Written in: ergonex/src/host/workspace.ts, ergonex/src/manifest.ts

Tests: passed: suite/ergonex-command.test.ts a root that does not exist is exit status 3, --home and $ERGONEX_HOME choose the root, and; passed: suite/ergonex-manifest.test.ts a manifest decodes into typed repositories with their paths, clone URLs, branches and work; passed: suite/ergonex-manifest.test.ts a manifest that does not decode is reported with the path of each field that is wrong, and; passed: suite/ergonex-manifest.test.ts a remote in the manifest needs no https:// where the domain says the rest, `owner/repo` is

Cited by: Ergonex, manifest, Intellectual Frontiers Workspaces

FR-002checkpassing

The target state MUST be the ergonex:Plan made from the manifest and the observed state (0002-workspace-model FR-021), and Ergonex MUST NOT rewrite the manifest, which ergonex setup creates once, as a starter, where there is none.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: ergonex init writes the starter manifest once and never rewrites it; ergonex setup (M6) may call the same function

Proved by: ergonex/suite/ergonex-command.test.ts

Written in: ergonex/src/commands/init.ts

Tests: passed: suite/ergonex-command.test.ts a root that does not exist is exit status 3, --home and $ERGONEX_HOME choose the root, and

Cited by: The ergonex command

Typed templates

FR-003checkpassing

A template MUST be a TypeScript function from the decoded data to a list of generated files, and MUST NOT be text in a template language: Ergonex MUST have no template parser, no eval, no new Function and no interpolation of data into code, so that a template is type-checked and cannot inject.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts: a template is a TypeScript function from data to files, and no code of the templates or the generator evaluates text or names a dotfiles manager

Proved by: ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-templates.test.ts

Written in: ergonex/src/render.ts, ergonex/src/templates/data.ts, ergonex/src/templates/mod.ts

Tests: passed: suite/ergonex-render.test.ts a group that would make a path with .. or a separator is refused as an error naming the te; passed: suite/ergonex-templates.test.ts no template parser, no eval, no new Function and no dotfiles manager is in the templates o

Cited by: Ergonex, render, templates/data, templates/mod

FR-004checkpassing

A generated file (ergonex:GeneratedFile) MUST have a RepoPath inside the root (the type refuses .., an absolute path and a drive), its content, a mode of 0644 or 0755 and a header, in the comment syntax of its format (a _generated member in JSON), naming its generator and saying it is not to be edited; its name MUST carry .auto., except a Git hook, whose name Git fixes and which lives in hooks/.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts, ergonex-render.test.ts: a generated file's path is refused where it holds .., is absolute, names a drive or lacks .auto. (a hook in .ergonex/hooks/ excepted), and a collision after case folding refuses both; its header names its generator

Proved by: ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-templates.test.ts

Tests: passed: suite/ergonex-render.test.ts a group that would make a path with .. or a separator is refused as an error naming the te; passed: suite/ergonex-templates.test.ts a generated file's path is refused where it holds .., is absolute, names a drive, lacks .a

Cited by: Ergonex, render

FR-005checkpassing

The templates MUST generate, from the manifest: a <group>.auto.code-workspace file at the root for each group of repositories the manifest names, AGENTS.auto.md at the root (FR-022), <home>/.ergonex/tools.auto.json (the resolved tool catalog), <home>/.ergonex/modules.auto.json (the registered modules), the hooks (FR-014) and, where FR-023 allows, .envrc.auto.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts, ergonex-render.test.ts: the templates make a code-workspace file for each group, AGENTS.auto.md, tools.auto.json, modules.auto.json, the hooks and .envrc.auto where allowed; tools.auto.json lists the catalog of the manifest

Proved by: ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-templates.test.ts

Written in: ergonex/src/templates/code-workspace.ts, ergonex/src/templates/json-files.ts, ergonex/src/templates/lefthook.ts

Tests: passed: suite/ergonex-render.test.ts render writes a code-workspace file for each group, with relative paths and no symbolic li; passed: suite/ergonex-render.test.ts .envrc.auto is generated only where the manifest wants direnv and a direnv is on the PATH,; passed: suite/ergonex-templates.test.ts the templates make a code-workspace file for each group, listing its folders by relative p; passed: suite/ergonex-templates.test.ts the templates make the guide, the registered modules, the resolved tools, the hooks and th

Cited by: Intellectual Frontiers Workspaces

FR-006checkpassing

A *.auto.code-workspace file MUST list each folder of its group by a path relative to the file, with / between segments, so that it opens the same on every operating system and no symbolic link is needed.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts, ergonex-render.test.ts: each folder of a group is listed by a path relative to the file with / between segments

Proved by: ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-templates.test.ts

Tests: passed: suite/ergonex-render.test.ts render writes a code-workspace file for each group, with relative paths and no symbolic li; passed: suite/ergonex-templates.test.ts the templates make a code-workspace file for each group, listing its folders by relative p

FR-007checkpassing

A generated file MUST be deterministic: the same data MUST give the same bytes, with no time, no host name, no user name and no absolute path of the user's computer in its content, in UTF-8 without a byte-order mark, with LF line endings and one final newline, whatever the operating system.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts: the same data gives the same bytes (UTF-8, no byte-order mark, LF, one final newline, no time, host or user name); ergonex-render.test.ts: Bun and Node 26 make the same bytes

Proved by: ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-templates.test.ts

Tests: passed: suite/ergonex-render.test.ts the generated files are the same bytes from Bun and from Node 26, whichever runtime made t; passed: suite/ergonex-templates.test.ts a generated file is the same bytes for the same data: UTF-8 with no byte-order mark, LF li

Cited by: Ergonex, render, templates/mod

FR-008checkpassing

A generated file MUST NOT be committed into a repository that is not the workspace's own, and Ergonex MUST NOT write one inside a repository's working tree.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts: a file inside a repository's working tree is refused; ergonex-render.test.ts: a group whose name would make such a path or one outside the root is refused and nothing is written

Proved by: ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-templates.test.ts

Tests: passed: suite/ergonex-render.test.ts a group that would make a path with .. or a separator is refused as an error naming the te; passed: suite/ergonex-templates.test.ts a generated file's path is refused where it holds .., is absolute, names a drive, lacks .a

Cited by: Ergonex, render

The state record, verify and render

FR-009checkpassing

The state record (ergonex:StateRecord) MUST be <state>/state.auto.json, in the state folder of commons 0031-install-locations, decoded as typed data, and MUST hold the path, the SHA-256 and the generator of each generated file as it was written, the hash of the last plan, the version of Ergonex, and the day each tool or module outside the catalog was first seen.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-record.test.ts: the state record holds the hash and generator of each file, the plan's hash, the version and the first-seen days, and reads back the same bytes; ergonex-render.test.ts: render writes it; ergonex doctor and ergonex tools fill the first-seen days and never restart them (ergonex-wiring.test.ts)

Proved by: ergonex/suite/ergonex-record.test.ts, ergonex/suite/ergonex-render.test.ts

Written in: ergonex/src/commands/verify.ts, ergonex/src/host/files.ts, ergonex/src/state-record.ts

Tests: passed: suite/ergonex-record.test.ts the state record holds the hash and generator of each file, the plan's hash, the version a; passed: suite/ergonex-render.test.ts verify finds a hand edit (error), a missing file, an unrecorded .auto. file and a drift (w

Cited by: Ergonex, state-record, Intellectual Frontiers Workspaces

FR-010checkpassing

ergonex verify MUST compare the disk with the record and the record with what the templates give now, and MUST report: a generated file whose bytes differ from the record (a hand edit) as an ergonex:Error, a recorded file that is missing, an .auto. file the record does not hold, and a file the templates would now write differently (a drift) each as an ergonex:Warning; it MUST change nothing.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-record.test.ts, ergonex-render.test.ts: verify reports a hand edit as an error and a missing, an unrecorded and a drifted file as warnings, and changes nothing

Proved by: ergonex/suite/ergonex-record.test.ts, ergonex/suite/ergonex-render.test.ts

Tests: passed: suite/ergonex-record.test.ts verify reports a hand edit as an error, and a missing recorded file, an unrecorded .auto. ; passed: suite/ergonex-render.test.ts verify finds a hand edit (error), a missing file, an unrecorded .auto. file and a drift (w

Cited by: state-record, The ergonex command, Intellectual Frontiers Workspaces

FR-011checkpassing

IF a generated file's bytes differ from the state record, THEN render and apply MUST NOT overwrite or remove it and MUST report it as refused with its path, unless the run says --force.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-render.test.ts: render and apply leave a hand-edited generated file as it is and say so, and render --force replaces it

Proved by: ergonex/suite/ergonex-render.test.ts

Tests: passed: suite/ergonex-render.test.ts verify finds a hand edit (error), a missing file, an unrecorded .auto. file and a drift (w

Cited by: Ergonex, state-record

FR-012checkpassing

ergonex render MUST write the generated files, and ergonex render --check MUST write nothing, name each file that would change and end with the exit status ergonex:Findings, and --dry-run MUST show the difference as a unified diff.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-render.test.ts: render --check writes nothing, names each file that would change and ends with findings; --diff shows a unified diff and writes nothing

Proved by: ergonex/suite/ergonex-record.test.ts, ergonex/suite/ergonex-render.test.ts

Written in: ergonex/src/diff.ts

Tests: passed: suite/ergonex-record.test.ts a unified diff names the file, has hunks with three lines of context, and is empty where n; passed: suite/ergonex-render.test.ts render writes a code-workspace file for each group, with relative paths and no symbolic li; passed: suite/ergonex-render.test.ts verify finds a hand edit (error), a missing file, an unrecorded .auto. file and a drift (w

Cited by: diff, Ergonex, The ergonex command

Git configuration and hooks

FR-013checkpassing

Ergonex MUST set Git's configuration only in each managed repository's own local configuration, each setting an ergonex:ConfigureRepo action of the plan: core.hooksPath as the absolute path of <home>/.ergonex/hooks with / between segments, the commit signing the policy requires (commit.gpgsign, gpg.format as openpgp or ssh, and the key the manifest names), user.name and user.email where the manifest names them, and on Windows core.longpaths; it MUST NOT write to the global or the system configuration, and MUST NOT remove a setting it did not set.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: apply sets core.hooksPath, the signing settings, user.name, user.email and, on Windows, core.longpaths in the repository's own configuration, replaces another hooks path, and writes nothing to the user's global configuration (the Windows setting is not run here: Windows is the CI's)

Proved by: ergonex/suite/ergonex-apply.test.ts, ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-templates.test.ts

Written in: ergonex/src/templates/hooks.ts

Tests: passed: suite/ergonex-apply.test.ts apply sets the hooks path and the policy's settings in the repository's own configuration ; passed: suite/ergonex-render.test.ts the commit-msg hook, run by Git through core.hooksPath, stops a commit that names no issue; passed: suite/ergonex-templates.test.ts the settings of a repository's local configuration are the hooks path, the signing the pol

Cited by: desired, Ergonex, Intellectual Frontiers Workspaces

FR-014checkpassing

The hooks MUST be generated into <home>/.ergonex/hooks/ as POSIX sh scripts of mode 0755 (Git for Windows runs hooks with its own sh): pre-commit (the plaintext-token scan of the staged changes, 0002-workspace-model FR-031), commit-msg (the issue named by every commit, commons 0020-ifccm) and pre-push (signed commits where the policy requires them), each running its checker with the runtime of the workspace.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts: the three hooks are POSIX sh scripts of mode 0755 accepted by sh -n; ergonex-render.test.ts: Git runs them through core.hooksPath and the commit-msg hook stops a commit that names no issue; the pre-commit hook's scan is wired in at commands/hook.ts CHECKERS; ergonex-wiring.test.ts: the pre-commit hook runs the plaintext-token scan of the staged changes (host/staged.ts, scan/secrets.ts)

Proved by: ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-templates.test.ts, ergonex/suite/ergonex-wiring.test.ts

Written in: ergonex/src/commands/hook.ts

Tests: passed: suite/ergonex-render.test.ts the pre-push hook says an unsigned commit is a warning where signed commits are required a; passed: suite/ergonex-render.test.ts the commit-msg hook, run by Git through core.hooksPath, stops a commit that names no issue; passed: suite/ergonex-templates.test.ts the templates make the guide, the registered modules, the resolved tools, the hooks and th; passed: suite/ergonex-templates.test.ts each hook is a POSIX sh script that only reads; with no checker it fails where a regulated; passed: suite/ergonex-templates.test.ts each hook script is accepted by sh -n and 1 more

Cited by: Ergonex, templates/mod, The ergonex command

FR-015checkpassing

A hook MUST only read: it MUST NOT change the commit, the tree or the configuration, and MUST NOT use the network; and IF a hook cannot run its checker, THEN it MUST exit non-zero and say why where the manifest names a regulated domain, and exit zero with the same message on standard error elsewhere.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts, ergonex-render.test.ts: a hook only reads; with no checker it exits non-zero with the reason where a regulated domain is named and exits zero with the same message elsewhere, run by Git with no bun, node or ergonex on the PATH

Proved by: ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-templates.test.ts

Tests: passed: suite/ergonex-render.test.ts a hook that cannot run its checker (no bun, no node, no ergonex) fails with the reason whe; passed: suite/ergonex-templates.test.ts each hook is a POSIX sh script that only reads; with no checker it fails where a regulated

Cited by: Ergonex, policy, The ergonex command

FR-016checkpassing

WHERE the user asks with ergonex setup --git-include, Ergonex MUST add to the user's global Git configuration one marked [include] of a file generated in the workspace, after showing the exact change and asking, and MUST NOT otherwise read or write it; this and FR-019 are the only writes outside the root, besides the Windows long-path setting (0001-ergonex FR-017).

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-setup.test.ts: setup --git-include shows the exact change and asks, writes only after a yes (no terminal and no --yes is a usage error before any change), leaves one marked block where run twice and the block comes out exactly; the file is a real configuration that real git config reads back; ergonex-wiring.test.ts: through ergonex as a real program

Proved by: ergonex/suite/ergonex-setup.test.ts, ergonex/suite/ergonex-wiring.test.ts

Written in: ergonex/src/setup/gitconfig.ts, ergonex/src/templates/git-include.ts

Tests: passed: suite/ergonex-setup.test.ts setup --git-include shows the exact change and asks first; a no, or no terminal and no --y; passed: suite/ergonex-setup.test.ts the include block is one marked block that is replaced, never doubled, and that is removed; passed: suite/ergonex-wiring.test.ts ergonex setup --git-include adds one marked include of the generated file to the global Gi

Cited by: The ergonex command

The shell snippet

FR-017checkpassing

ergonex shell print <bash|zsh|fish|pwsh|nu> MUST print the snippet for that shell on standard output and nothing else, MUST write no file and change nothing, and MUST exit 2 for another shell.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: ergonex shell <bash|zsh|fish|pwsh|nu> prints the snippet on standard output and writes no file, and another shell is exit status 2

Proved by: ergonex/suite/ergonex-command.test.ts, ergonex/suite/ergonex-shell.test.ts

Written in: ergonex/src/commands/shell.ts, ergonex/src/shell/mod.ts, ergonex/src/shell/snippet.ts

Tests: passed: suite/ergonex-command.test.ts ergonex shell print <shell> prints the snippet on standard output and writes nothing, no f; passed: suite/ergonex-shell.test.ts a root named for one run is one word in every shell, whatever it holds, and the snippet is; passed: suite/ergonex-shell.test.ts the POSIX snippets are accepted by bash -n and sh -n, and the default snippet holds no abs; passed: suite/ergonex-shell.test.ts sourced by a real bash, the snippet sets the root once, puts ~/.local/bin, where the shims

Cited by: Ergonex, shell/snippet, The ergonex command

FR-018checkpassing

The snippet MUST do four things and no more: export ERGONEX_HOME where it is not set, add ~/.local/bin (on Windows, <data>/tools/bin), where the shims of the pinned tools and of the ergonex-* modules are, to the PATH, define the completions of ergonex, and define one function, wcd, that changes to a repository of the workspace by its name.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-shell.test.ts: the snippet of each shell does the four things and defines one function; sourced by a real bash it sets the root once, puts the tools folder on the PATH once and wcd changes to a repository by name (zsh, fish, PowerShell and Nushell are read as text: they are not installed here)

Proved by: ergonex/suite/ergonex-command.test.ts, ergonex/suite/ergonex-shell.test.ts

Tests: passed: suite/ergonex-command.test.ts ergonex shell print <shell> prints the snippet on standard output and writes nothing, no f; passed: suite/ergonex-shell.test.ts sourced by a real bash, the snippet sets the root once, puts ~/.local/bin, where the shims; passed: suite/ergonex-shell.test.ts each snippet exports the root where it is not set, adds ~/.local/bin (the shims of the too

Cited by: Ergonex, shell/snippet

FR-019checkpassing

ergonex shell install MUST write one block (and with --dry-run show it as a unified diff) between the lines # >>> ergonex >>> and # <<< ergonex <<< in the shell's start-up file (~/.bashrc, ~/.zshrc, ~/.config/fish/conf.d/ergonex.fish, the PowerShell $PROFILE, or the Nushell config.nu, or the file --rc names) and ask, MUST write only after a yes (and exit 2 where there is no terminal and no --yes), MUST leave one block where it is run twice, and --uninstall MUST remove exactly that block and nothing else.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-shell.test.ts, ergonex-command.test.ts: --install shows a unified diff of one marked block and writes only after a yes or --yes (a usage failure with no terminal and no --yes), twice leaves one block, --uninstall removes exactly it and leaves a file with other text, CRLF or no final newline as it was

Proved by: ergonex/suite/ergonex-command.test.ts, ergonex/suite/ergonex-shell.test.ts

Written in: ergonex/src/shell/block.ts

Tests: passed: suite/ergonex-command.test.ts ergonex shell install writes one block (--dry-run shows its diff and writes nothing), twic; passed: suite/ergonex-shell.test.ts each shell's start-up file is the one the specification names, the --rc file aside; passed: suite/ergonex-shell.test.ts install and uninstall keep a file that is empty, has no final newline or uses CRLF as it w; passed: suite/ergonex-shell.test.ts install writes one marked block, a second install leaves one, and uninstall removes exactl

Cited by: diff, Ergonex, shell/block, The ergonex command

What is not managed

FR-020checkpassing

Ergonex MUST NOT read, write or manage, outside FR-016, FR-019 and the Windows long-path setting: the global and system Git configuration (~/.gitconfig, $XDG_CONFIG_HOME/git, /etc/gitconfig), any shell start-up file, ~/.ssh, the settings of an editor or an IDE, a credential store, the user's environment variables or PATH as the system stores them, a system package manager, or any file outside the root.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-boundaries.test.ts, ergonex-apply.test.ts: nothing of the global or system Git configuration, ~/.ssh, a credential store or a user's file is read or written but the one marked block of a start-up file on request

Proved by: ergonex/suite/ergonex-apply.test.ts, ergonex/suite/ergonex-boundaries.test.ts, ergonex/suite/ergonex-command.test.ts

Tests: passed: suite/ergonex-apply.test.ts apply sets the hooks path and the policy's settings in the repository's own configuration ; passed: suite/ergonex-boundaries.test.ts no code of src/ names ~/.ssh, a credential store, or the user's or the system's Git config; passed: suite/ergonex-command.test.ts ergonex shell install writes one block (--dry-run shows its diff and writes nothing), twic

Not a dependency

FR-021checkpassing

Ergonex MUST NOT import, run or require chezmoi, or any program that templates dotfiles; the credit in 0002-workspace-model FR-046 is for the ideas.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts: no code under workspaces/ imports, runs or names a dotfiles manager

Proved by: ergonex/suite/ergonex-templates.test.ts

Tests: passed: suite/ergonex-templates.test.ts no template parser, no eval, no new Function and no dotfiles manager is in the templates o

Generated guidance

FR-022checkpassing

AGENTS.auto.md MUST tell an agent the layout of the workspace, its rules (plan before apply, fast-forward only, one issue for every commit, no credential in a file) and its commands, from the manifest, with no secret and no absolute path of the user's computer.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts: AGENTS.auto.md tells an agent the layout, the rules and the commands from the manifest, with no secret and no absolute path of the computer

Proved by: ergonex/suite/ergonex-templates.test.ts

Written in: ergonex/src/templates/agents.ts

Tests: passed: suite/ergonex-templates.test.ts the templates make the guide, the registered modules, the resolved tools, the hooks and th; passed: suite/ergonex-templates.test.ts the guide tells an agent the layout, the rules and the commands from the manifest, with no

Cited by: Ergonex, templates/mod

FR-023checkpassing

.envrc.auto MUST be generated only where the manifest says direnv is wanted and a probe finds direnv, and it MUST only add ~/.local/bin to the PATH.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts, ergonex-render.test.ts: .envrc.auto only where direnv is wanted and found, and it only adds the tools folder to the PATH by a relative path

Proved by: ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-templates.test.ts

Written in: ergonex/src/templates/envrc.ts

Tests: passed: suite/ergonex-render.test.ts .envrc.auto is generated only where the manifest wants direnv and a direnv is on the PATH,; passed: suite/ergonex-templates.test.ts .envrc.auto exists only where direnv is wanted and found, and only adds the tools folder t

Cited by: Ergonex, templates/data, templates/mod

FR-024checkno test run

The templates MUST also generate lefthook.auto.yml at the root, which calls the three generated hooks by their relative path and holds no checker of its own, for a person who runs lefthook in the workspace's own repository.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts: lefthook.auto.yml calls the three generated hooks by their relative path and holds no checker

FR-025checkno test run

A generated hook MUST run ergonex hook <name> with --home the root it finds from its own place (it holds no absolute path), MUST send what it prints to standard error, and MUST read its status as 0 (go on), 1 (stop) or anything else (it cannot run its checker, FR-015).

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-templates.test.ts, ergonex-render.test.ts: a hook finds the root from its own place, holds no absolute path, sends the checker's output to standard error and reads its status as go on, stop or cannot run

Cited by: The ergonex command

FR-026checkpassing

ergonex shell install MUST NOT create a start-up file that does not exist: where the shell's start-up file is absent it MUST write nothing and say how to create it (the command to run and the path), and --uninstall MUST NOT create one either.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-shell.test.ts: installBlock refuses a file that is not there (absent) and takes an empty one, and the command that creates a start-up file is said for each shell with a path quoted for it; ergonex-command.test.ts: ergonex shell --install, run as a program, never creates the start-up file or its folder (exit status 3, the path and the command named, the user's home as it was, with --yes or without), --uninstall creates none, and a file the person made takes the block

Proved by: ergonex/suite/ergonex-command.test.ts, ergonex/suite/ergonex-shell.test.ts

Tests: passed: suite/ergonex-command.test.ts ergonex shell install, run as a program, never creates the shell's own start-up file or it; passed: suite/ergonex-shell.test.ts a start-up file that is not there is never made by install, and the command that makes it

Cited by: shell/block

Out of scope

  • The command's modules, discovery and exit codes: 0001-ergonex. The layout, portability, plan and policy: 0002-workspace-model.
  • The rules of commits and branches the hooks enforce: commons 0020-ifccm.

Edge cases

  • A template that returns a path with .. or a drive: its file does not type-check as a RepoPath and the run stops before writing, per FR-004.
  • A hand-edited AGENTS.auto.md: ergonex verify reports an error, render refuses to overwrite it, and render --force replaces it, per FR-010 and FR-011.
  • Two generated files whose paths differ only in case: refused as in 0002-workspace-model FR-011, per FR-004.
  • A repository whose local configuration already sets core.hooksPath to another folder: replaced by ergonex:ConfigureRepo and shown in the plan, per FR-013.
  • ergonex shell install run twice: one block, per FR-019.
  • ergonex shell print nu where the user's rc file already has text around the block: that text is not touched on ergonex shell uninstall, per FR-019.
  • A workspace on Windows where a file is CRLF after a checkout: a generated file is LF, and verify compares bytes, per FR-007.
  • A manifest field of the wrong type: reported with its path and nothing is written, per FR-001.

Scenarios

  • Given a manifest that names two groups of repositories, When ergonex render runs, Then two *.auto.code-workspace files are at the root, each listing its folders by relative paths, and no symbolic link is made (FR-005, FR-006).
  • Given a rendered workspace, When ergonex render --check runs and nothing has changed, Then it writes nothing and exits with no findings, and after the manifest changes it names the files that would change (FR-012, FR-007).
  • Given a generated file edited by hand, When ergonex verify runs, Then it reports an error naming the file, and ergonex render leaves the file as it is (FR-010, FR-011).
  • Given a managed repository, When the plan is applied, Then its local configuration holds the hooks path and nothing is written to the user's global Git configuration (FR-013, FR-020).
  • Given a regulated manifest and a machine with no bun or node, When a commit is made, Then the commit-msg hook fails with the reason (FR-014, FR-015).
  • Given a shell name, When ergonex shell print bash runs, Then the snippet is on standard output, no file has changed, and the snippet holds the four things and no other (FR-017, FR-018).
  • Given a start-up file with other text, When ergonex shell install bash and later ergonex shell uninstall bash run, Then the file is again as it was (FR-019).

Assumptions

  • chezmoi's ideas are credited and not used as code: the typed templates are TypeScript functions because a function is checked by the compiler and a template language is not (FR-003, FR-021).
  • Git for Windows ships sh, which runs the hooks on Windows (FR-014); a Windows machine without Git for Windows has no Git to configure.
  • A group of repositories in the manifest replaces the symlinked workspace files of the earlier tools (0002-workspace-model FR-013).
  • The generated hooks run the TypeScript the library holds with Bun or Node 26 until a compiled checker exists (owner decision of 2026-11-17, issue #10).
  • This specification is Active from 2026-11-17: the requirements it does not yet prove say so in the enforcement register.

Open questions

None.

Key entities

  • Manifest - the typed source state, workspace.ts.
  • GeneratedFile - a file a template makes, with its path, content, mode and header.
  • StateRecord - the hashes of what was written, and the first-seen days.
  • Hook - a generated script Git runs before a commit or a push.
  • Snippet - the lines ergonex shell print prints for a shell.

Success criteria

SC-001success criterion

A hand edit or a drift of any generated file is found by ergonex verify, and no run overwrites a hand edit without --force.

SC-002success criterion

Nothing outside the workspace changes unless the user asked for it and saw the exact change first.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

desired, diff, Ergonex, manifest, policy, render, shell/block, shell/snippet, state-record, templates/data, templates/mod, The ergonex command, Intellectual Frontiers Workspaces

Titles, headings, exports, tables, columns and requirements. Esc closes.