IF Commons GitHub

The ergonex command

0001Active

0001-ergonex · owner if · domain commons

The command

FR-001checkpassing

The program MUST be commons/ergonex/src/ergonex.ts on @intellectual-frontiers/headless, the library MUST be in the same folder, commons/ergonex/src/, the commands in commons/ergonex/src/commands/ (the tree is commands/program.ts) and the values the commands share in commons/ergonex/src/modules/, the package's bin MUST be ergonex, and the package MUST depend on Headless by its package name, through its exports only (./governance, ./logical, ./cli).

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts, ergonex-boundaries.test.ts: the controller is workspaces/ergonex.ts, the commands are in commands/, the contract in modules/, and the package's bin names ergonex through node/ergonex.mjs

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

Written in: ergonex/about.ts, ergonex/library.ts, ergonex/src/commands/program.ts, ergonex/src/mod.ts

Tests: passed: suite/ergonex-command.test.ts ergonex --help says it manages only Intellectual Frontiers Workspaces and is not an IFC or; passed: suite/ergonex-command.test.ts the same report comes from Bun and from Node 26, through the controller and through the la

Cited by: commands/program, Ergonex

FR-002checkpassing

ergonex manages only Intellectual Frontiers Workspaces; it is not a general IFC or Mizan controller and does not front ifc, and ergonex --help MUST say so in these words: "It manages only Intellectual Frontiers Workspaces; it is not a general IFC or Mizan controller and does not front ifc."

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: ergonex --help says in these words that ergonex manages only Intellectual Frontiers Workspaces, is not a general IFC or Mizan controller and does not front ifc

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

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

Tests: passed: suite/ergonex-command.test.ts ergonex --help says it manages only Intellectual Frontiers Workspaces and is not an IFC or

Cited by: Intellectual Frontiers Workspaces

FR-003checkpassing

ergonex help [command] MUST describe the program and each command from its declaration (Headless generates the help, the completions of ergonex completions <shell> and the man page of ergonex man), ergonex with no command MUST say in plain words what to do next (ergonex start, 0004-onboarding FR-003), and ergonex modules MUST list every module with its name, its source (ergonex:BuiltIn, ergonex:Registered or ergonex:Path) and its summary.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: ergonex <name> runs the module, ergonex help describes the command, and ergonex modules names every module with its name, its source (ergonex:BuiltIn, ergonex:Registered or ergonex:Path) and its summary

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

Written in: ergonex/src/modules/registry.ts

Tests: passed: suite/ergonex-command.test.ts ergonex --help says it manages only Intellectual Frontiers Workspaces and is not an IFC or; passed: suite/ergonex-command.test.ts an executable ergonex-* on the PATH is listed with the source ergonex:Path and not run, ru; passed: suite/ergonex-modules.test.ts a module is found in the order built-in, registered, path; the first runs and a module of

Cited by: commands/program, Ergonex, modules/registry

Modules

FR-004checkpassing

A word that is not a command of the program MUST be looked for as a module in the order of ergonex:precedence of its source: first among the built-in modules (the words of the program's own tree), then among the modules the workspace registers in <home>/.ergonex/modules.auto.json, then among the executables named ergonex-* on the PATH (with the extensions of PATHEXT on Windows), as Git finds git-foo for git foo; the first found MUST run, and a module of a later source that it hides MUST be an ergonex:Informational finding.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-modules.test.ts, ergonex-command.test.ts: a module is found built-in, then registered, then on the PATH, the first runs and the one it hides is an informational finding; the order is the ontology's

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

Written in: ergonex/src/host/discovery.ts, ergonex/src/modules/mod.ts

Tests: passed: suite/ergonex-command.test.ts an executable ergonex-* on the PATH is listed with the source ergonex:Path and not run, ru; passed: suite/ergonex-command.test.ts a module the workspace registers is found before the PATH, run, and checked against its pi; passed: suite/ergonex-modules.test.ts a module is found in the order built-in, registered, path; the first runs and a module of ; passed: suite/ergonex-modules.test.ts the order of the sources and the four statuses are the ones of the ontology's code lists

Cited by: Ergonex, modules/registry

FR-005checkpassing

A module name MUST be lower-case letters, digits and hyphens, beginning with a letter, and a word with any other character, with a path separator or longer than 32 characters MUST be refused with exit status ergonex:Usage (it is not a command of the program) and never passed to a shell.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-modules.test.ts, ergonex-command.test.ts: a name that is not lower-case letters, digits and hyphens from a letter, or longer than 32, is refused with exit status 2 and never run

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

Written in: ergonex/src/modules/name.ts

Tests: passed: suite/ergonex-command.test.ts a typo of a module name is exit status 2 with the nearest names, a name that is not a modu; passed: suite/ergonex-modules.test.ts a module name is lower-case letters, digits and hyphens, beginning with a letter, at most

Cited by: Ergonex, modules/name

FR-006checkpassing

IF no command or module is named as given, THEN ergonex MUST exit with ergonex:Usage and name the nearest command where one is within an edit distance of two of it.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-modules.test.ts, ergonex-command.test.ts: an unknown name is exit status 2 with up to three modules within an edit distance of two, or that none is near

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

Tests: passed: suite/ergonex-command.test.ts a typo of a module name is exit status 2 with the nearest names, a name that is not a modu; passed: suite/ergonex-modules.test.ts an unknown name is answered with up to three modules within an edit distance of two, neare

Cited by: Ergonex, modules/name

FR-007checkpassing

A command MUST be declared once with Headless: its name and summary, its options and operands (--home and its own; the options every command takes by its effect are Headless'), its examples and its action (kind, effect, idempotent, dryRun, check, and a reach policy: its channels, whether it is read-only, idempotent, needs a terminal, whom it runs as, how it is confirmed), and a body that returns a Result of a Report or a Failure; the model MUST have no problem (modelProblems, with a reach policy required of every action), with no any, and a switch over a union MUST be exhaustive.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-modules.test.ts: ErgonexModule and Command are typed, defineCommand parses the options once into a typed value, and a switch over a union of sources or statuses is exhaustive (the compiler and the linter)

Proved by: ergonex/suite/ergonex-headless.test.ts, ergonex/suite/ergonex-modules.test.ts

Written in: ergonex/src/commands/define.ts, ergonex/src/modules/types.ts

Tests: passed: suite/ergonex-headless.test.ts the program's tree is a well-formed Headless model: no duplicate or reserved word, every a; passed: suite/ergonex-modules.test.ts a command declared on Headless parses its words once into a typed value, answers help with

Cited by: commands/define, Ergonex, modules/types

FR-008checkpassing

An external module MUST answer --ergonex-manifest on standard output with JSON (its name, its summary, its commands and the version of this contract) that a typed decoder checks and whose JSON Schema is generated from the type, and an external module that does not answer within five seconds, or whose answer does not decode, MUST run as an opaque command whose exit status is recorded in the evidence.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-modules.test.ts, ergonex-command.test.ts: an external module's --ergonex-manifest answer is checked by a typed decoder and its JSON Schema is made from the same fields; a module that does not answer or whose answer does not decode is opaque, runs, and its exit status is passed on and recorded

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

Written in: ergonex/src/modules/external.ts

Tests: passed: suite/ergonex-command.test.ts an executable ergonex-* on the PATH is listed with the source ergonex:Path and not run, ru; passed: suite/ergonex-modules.test.ts an external module's answer to --ergonex-manifest is checked by a typed decoder, and its J

Cited by: Ergonex, modules/external

FR-009checkpassing

ergonex modules and ergonex help MUST NOT run a module found on the PATH unless --probe is given, so that listing never runs a program the workspace has not approved.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: ergonex modules and ergonex help run nothing found on the PATH; --probe runs each only to ask for --ergonex-manifest

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

Tests: passed: suite/ergonex-command.test.ts an executable ergonex-* on the PATH is listed with the source ergonex:Path and not run, ru

FR-010checkpassing

A run MUST end with a status of Headless' table: ergonex:Ok (0), ergonex:Findings (1), ergonex:Usage (2), ergonex:Environment (3) and, for a check that finds something pending, 4: 1 where there is at least one finding of severity ergonex:Error or ergonex:Warning (each is a failed problem of the run, with the stable code of its rule, E- and the rule's words: ergonex/repository-diverged is E-REPOSITORY-DIVERGED) and no ergonex:Informational finding alone makes it 1 (it is a warning, which Headless never makes a failure); 2 for an unknown command, option or argument, a refused action, or a body that says its words do not fit; 3 where the host cannot do it (no git, an unsupported runtime, a root that does not exist or cannot be written, an evidence record that cannot be written); an opaque external module's own status MUST be passed on and recorded. Every code MUST be explained: ergonex explain <code> says what happened, the likely cause and the fix, and a test proves that every rule the sources write has an entry.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-modules.test.ts, ergonex-command.test.ts, ergonex-apply.test.ts: exit status 0 ok, 1 findings (a warning or an error; an informational one alone is 0), 2 usage, 3 environment, with the numbers of the ontology

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

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

Tests: passed: suite/ergonex-command.test.ts an executable ergonex-* on the PATH is listed with the source ergonex:Path and not run, ru; passed: suite/ergonex-command.test.ts a typo of a module name is exit status 2 with the nearest names, a name that is not a modu; 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-headless.test.ts a run writes its report on standard output and its problems and verdict on standard error,; passed: suite/ergonex-headless.test.ts every problem code the sources can raise is explained, and the catalogue is well formed and 2 more

Cited by: commands/catalogue, commands/define, findings, Ergonex, modules/types

FR-011checkpassing

A registered module MUST be named in modules.auto.json with the path of its program and MAY carry the SHA-256 of that program, which ergonex MUST check before running it and MUST refuse the module, with exit status ergonex:Environment, where it differs; a registered module or one on the PATH that the catalog does not list MUST be a finding as in 0002-workspace-model FR-033.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: a registered module of modules.auto.json is found before the PATH and its program is refused with exit status 3 where its SHA-256 differs from the pin; the finding for a module the catalog does not list is in ergonex doctor (ergonex-wiring.test.ts)

Proved by: ergonex/suite/ergonex-command.test.ts, ergonex/suite/ergonex-modules.test.ts, ergonex/suite/ergonex-scan.test.ts, ergonex/suite/ergonex-wiring.test.ts

Tests: passed: suite/ergonex-command.test.ts a module the workspace registers is found before the PATH, run, and checked against its pi; passed: suite/ergonex-modules.test.ts a registered module names its program and may pin its SHA-256; a name, a hash or a duplica; passed: suite/ergonex-scan.test.ts an ergonex-* executable outside the catalog is informational for 90 days and a warning aft; passed: suite/ergonex-scan.test.ts ergonex-* executables are found on a real PATH, in the order of the path, the first of eac; passed: suite/ergonex-wiring.test.ts an ergonex-* module on the PATH that the catalog does not list is informational from the d

Cited by: Ergonex, modules/registry

The commands

FR-012checkpassing

ergonex plan MUST be a report that shows the typed plan and changes nothing, and ergonex apply MUST be an action, safe to repeat, that carries it out as 0002-workspace-model FR-022 to FR-030 say, with no action of a kind that is ergonex:hostChange and no destructive action without --allow-destructive.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: plan shows the typed plan and changes nothing, apply carries it out with no action that changes the host and no destructive action without --allow-destructive

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

Written in: ergonex/src/commands/common.ts, ergonex/src/commands/plan.ts

Tests: passed: suite/ergonex-apply.test.ts a plan clones the missing repository at the path that mirrors its URL and changes nothing;; passed: suite/ergonex-apply.test.ts a generated file that is no longer generated is removed only with --allow-destructive and

FR-013checkpassing

ergonex status MUST list every repository of the manifest, one line each in the order of its path, with its ergonex:RepoState, how many commits it is ahead and behind, its stashes, its untracked files and whether it is locked; it MUST NOT use the network unless --fetch is given, and it MUST exit with ergonex:Findings where a repository is ergonex:Diverged, ergonex:Locked, ergonex:WrongRemote or ergonex:NotARepo.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: status lists every repository in the order of its path with its state, ahead and behind, stashes, untracked files and lock, uses no network without --fetch, and ends with findings for a diverged, locked, wrong-remote or not-a-repository one

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

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

Tests: passed: suite/ergonex-apply.test.ts a repository with uncommitted changes, with commits of its own or diverged is skipped with; passed: suite/ergonex-apply.test.ts a folder that holds another remote's clone, or that is not a repository, is refused and ne; passed: suite/ergonex-apply.test.ts a repository that is behind is fast-forwarded by apply, status shows it before and after,

FR-014checkpassing

ergonex doctor MUST check the runtime and the tools, the layout and the portability of every path, the file system, the policy (the plaintext-token scan, signed commits, tools and modules outside the catalog) and the generated files, and MUST report each check as ok, suggest (an ergonex:Informational finding), warn (an ergonex:Warning) or error (an ergonex:Error), each with what to do.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-render.test.ts, ergonex-record.test.ts: doctor checks the runtime and tools, the layout and portability, the file system, the hooks and the generated files, each ok, suggest, warn or error with what to do; the plaintext-token scan, signed commits and the catalog are wired in at commands/doctor.ts DOCTOR_CHECKS and proved in ergonex-wiring.test.ts

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

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

Tests: passed: suite/ergonex-record.test.ts the runtime, the tools and the hooks are checked, each with what to do: git is required, t; passed: suite/ergonex-render.test.ts doctor checks the runtime, the layout, the file system, the hooks and the generated files,; passed: suite/ergonex-wiring.test.ts doctor finds a plaintext token in a repository's local Git configuration as an error that

Cited by: doctor, Ergonex

FR-015checkpassing

ergonex verify (a report) and ergonex render (an action that previews with --dry-run and checks with --check) MUST be as 0003-host FR-010 and FR-012 say, and ergonex tools MUST list the catalog and probe the tools that are installed or on the PATH against it and MUST install nothing.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-render.test.ts: verify and render as 0003-host FR-010 and FR-012 say; ergonex-wiring.test.ts: ergonex tools (run as a real program) lists the catalog of the manifest, verifies the installed tools against their records and the probes, exports OSCAL, SPDX and CycloneDX, and installs nothing

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

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

Tests: passed: suite/ergonex-wiring.test.ts ergonex tools lists, verifies and exports the catalog and installs nothing; ergonex setup

FR-016checkpassing

ergonex worktree MUST have create, list and prune: create MUST make a worktree at the path of 0002-workspace-model FR-007 on a branch named for its issue (commons 0020-ifccm) only where another person or agent, or uncommitted work, is on the repository, and otherwise MUST say that the repository's own checkout is the place and make none unless --always is given; prune is destructive: it MUST remove only a worktree that has no uncommitted change and no unpushed commit, MUST preview with --dry-run, and MUST ask the person or be given --yes.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: worktree create makes a worktree at .worktrees/<host>/<path>/<repo>/<branch-slug> on an issue-named branch only where someone else or uncommitted work is on the repository (else it says the checkout is the place, unless --always), list shows them, prune removes only one with no uncommitted change and no unpushed commit, and only with --allow-destructive

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

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

Tests: passed: suite/ergonex-apply.test.ts worktree create makes a worktree only where someone else or uncommitted work is on the rep

Setup

FR-017checkpassing

ergonex setup MUST be the only command that installs a tool or changes the host: it MUST carry its plan out unless --dry-run is given, which shows the plan and changes nothing, and MUST record the run as an ergonex:Setup whose plan was shown and whose ergonex:applied says whether it was carried out; no other command MAY carry out an ergonex:InstallTool or an ergonex:ConfigureHost action.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-setup.test.ts: --dry-run shows the plan and changes nothing, setup carries the plan out, and the run is recorded with ergonex:applied and a not_run for a dry run; only setup carries out an InstallTool or a ConfigureHost; ergonex-wiring.test.ts: the same through the command, and setup takes the workspace's one lock file (<home>/.ergonex/ergonex.lock), the one apply takes, so that setup --apply and apply refuse while another run holds it

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

Written in: ergonex/src/commands/setup.ts, ergonex/src/setup/host/apply.ts, ergonex/src/setup/plan.ts

Tests: passed: suite/ergonex-apply.test.ts a generated file that is no longer generated is removed only with --allow-destructive and ; passed: suite/ergonex-setup.test.ts a dry run shows the plan and changes NOTHING: no root, no tool, no request to the host; passed: suite/ergonex-setup.test.ts only the kinds with a host change are InstallTool, SetSystemLongPaths and AddGitInclude, a; passed: suite/ergonex-tools.test.ts ergonex tools never installs: its arguments name no install and its run writes nothing; passed: suite/ergonex-wiring.test.ts ergonex tools lists, verifies and exports the catalog and installs nothing; ergonex setup and 1 more

Cited by: Intellectual Frontiers Workspaces, Ergonex host: typed templates, generated files and what is managed

FR-018checkpassing

ergonex setup MUST create the root and a starter manifest where there is none, install only the pinned artifacts of the catalog for this operating system and architecture (the version and the SHA-256 of each, 0002-workspace-model FR-039) into <home>/.ergonex/tools/, and MUST NOT install git, bun or node, which it verifies by a probe of their versions and, where one is missing or too old, names with the way to install it.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-setup.test.ts: setup creates the root and a starter manifest (never over one), installs only the pinned artifacts of the catalog for this system into .ergonex/tools/, and only probes git, bun and node, naming how to install one that is missing or old

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

Written in: ergonex/src/setup/starter.ts, ergonex/src/tools/args.ts, ergonex/src/tools/host/tools.ts

Tests: passed: suite/ergonex-setup.test.ts setup --apply creates the root and a starter manifest, installs only the pinned artifact i; passed: suite/ergonex-setup.test.ts setup --apply refuses an artifact whose hash differs from the pin, writes nothing of it, a; passed: suite/ergonex-setup.test.ts a probe that fails is a finding that says how to install the tool, and setup installs noth; passed: suite/ergonex-tools.test.ts a pinned artifact is fetched, its hash checked and the tool installed under the tools fold; passed: suite/ergonex-wiring.test.ts ergonex tools lists, verifies and exports the catalog and installs nothing; ergonex setup and 1 more

FR-019checkpassing

On Windows, ergonex setup MUST set core.longpaths in each managed repository's local configuration and, WHERE the process is elevated, MUST turn long paths on for the system, and WHERE it is not elevated MUST NOT try to elevate itself and MUST print the exact steps and exit with ergonex:Findings; it MUST treat a path of more than 259 characters as an error while long paths are off (0002-workspace-model FR-012).

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-setup.test.ts: on Windows setup sets core.longpaths in each cloned repository with real git, turns the system setting on only where elevated (the function that stands for reg add is given by the test), and where not elevated prints the exact steps and ends with findings; a path over 259 is an error

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

Tests: passed: suite/ergonex-setup.test.ts doctor's message that long paths are not enabled is informational while no path is over th; passed: suite/ergonex-setup.test.ts on Windows setup sets core.longpaths in each cloned repository and, not elevated, prints t; passed: suite/ergonex-setup.test.ts on Windows, elevated, setup turns the system setting on once, through the function that st

FR-020checkpassing

ergonex setup --git-include MUST carry out the global Git include of 0003-host FR-016 (after showing the exact change and, where a person can be asked, asking; where no one can be asked the flag is the consent), and ergonex shell install and ergonex shell uninstall (0003-host FR-019) MUST be the setup restricted to the shell snippet, with --dry-run showing the diff.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-wiring.test.ts: ergonex setup --git-include shows the exact change and writes the one marked include of the generated git.auto.conf only after --yes or a yes (a usage failure with no terminal and none; nothing on a dry run), twice leaves one; ergonex-command.test.ts, ergonex-shell.test.ts: ergonex shell --install and --uninstall are the setup restricted to the shell block, with a diff, a question and the same evidence

Proved by: ergonex/suite/ergonex-command.test.ts, ergonex/suite/ergonex-setup.test.ts, ergonex/suite/ergonex-wiring.test.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-setup.test.ts setup --git-include shows the exact change and asks first; a no, or no terminal and no --y; passed: suite/ergonex-wiring.test.ts ergonex setup --git-include adds one marked include of the generated file to the global Gi

Cited by: Intellectual Frontiers Workspaces

FR-021checkpassing

ergonex shell print <shell> MUST be as 0003-host FR-017 says: the snippet on standard output, nothing written.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: ergonex shell print <shell> prints the snippet on standard output and writes nothing

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

Tests: passed: suite/ergonex-command.test.ts ergonex shell print <shell> prints the snippet on standard output and writes nothing, no f

Options, output and runtime

FR-022checkpassing

Options MUST be parsed once at the boundary into a typed value, and every command MUST accept --home <dir> and Headless' options by its effect: --json (the one JSON document, headless.envelope/1), --quiet, --verbose, --no-color, --non-interactive and --help, --sarif (the findings as a SARIF 2.1.0 log, 0002-workspace-model FR-035) on a report, --dry-run on an action that previews, --check on one that checks, --yes on one that destroys; an option a command does not know MUST end in ergonex:Usage. The report MUST be on standard output and the problems, the verdict and the one next: command on standard error, and the run log and the hints MUST be under <XDG_STATE_HOME>/ergonex (log/, hints.json).

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-modules.test.ts, ergonex-command.test.ts: options are parsed once into a typed value, every command accepts --home, --json, --sarif, --no-color and --help, and an option a command does not know is exit status 2

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

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

Tests: passed: suite/ergonex-command.test.ts a typo of a module name is exit status 2 with the nearest names, a name that is not a modu; 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-headless.test.ts the program's tree is a well-formed Headless model: no duplicate or reserved word, every a; passed: suite/ergonex-headless.test.ts a run writes its report on standard output and its problems and verdict on standard error,; passed: suite/ergonex-modules.test.ts a command declared on Headless parses its words once into a typed value, answers help with and 1 more

Cited by: commands/define, Ergonex, modules/types

FR-023checkpassing

Every action that says it is idempotent MUST be: run again with nothing changed it MUST change nothing, and every run of a command MUST write its evidence record (0002-workspace-model FR-041); a command line that Headless refuses before it runs (ergonex:Usage) runs nothing and records nothing.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: every command is idempotent (a second apply and a second render change nothing); ergonex-command.test.ts: every run writes its evidence record, a usage run as not_run with its reason

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

Tests: passed: suite/ergonex-apply.test.ts apply is idempotent: a second run changes no file, no configuration and no state record; passed: suite/ergonex-command.test.ts every run of a command writes one evidence record in the shape of an IFQS record, a comman; passed: suite/ergonex-headless.test.ts a run writes its report on standard output and its problems and verdict on standard error,

Cited by: commands/define, Ergonex

FR-024checkpassing

ergonex MUST be TypeScript 7 and run on Bun by default and on Node 26 as the backup, from its .ts sources as they are; it MUST NOT run on, test on or document Deno; and it MUST have no any, no non-null !, errors as values (Result) and exhaustive switches.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: the same report from Bun and from Node 26, through the controller and the launcher with the loader hook of ifc; the library has no any, no non-null !, errors as values and exhaustive switches (tsc and the linter in CI); Deno is not run, tested or documented

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

Written in: ergonex/tools/check.ts

Tests: passed: suite/ergonex-command.test.ts the same report comes from Bun and from Node 26, through the controller and through the la

FR-025checkno test run

ergonex init MUST make the root and the workspace's own area and write the starter manifest (0003-host FR-002) where there is none, MUST install no tool and change nothing outside the root but what 0004-onboarding FR-002 says (ergonex itself put on the path, which --no-install leaves out), and run again MUST change nothing; ergonex setup MAY call it, and init and setup are the only commands that make the root.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: ergonex init makes the root and the area and writes the starter manifest once, and run again changes nothing

FR-026checkpassing

Every run MUST write its evidence record (FR-023) but the printing form of ergonex shell print <shell> (it writes no file, 0003-host FR-017, and a start-up file may run it at every start), a preview (--dry-run), ergonex help and the help of a command (they run nothing), a Git hook that ergonex hook runs (a hook only reads, 0003-host FR-015), and a run for which <home>/.ergonex/ does not exist, which has no place to keep it (ergonex init, which makes the area, writes its record).

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts, ergonex-render.test.ts: ergonex shell print <shell> and a hook write no evidence record; every other run does

Proved by: ergonex/suite/ergonex-command.test.ts, ergonex/suite/ergonex-render.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-render.test.ts the commit-msg hook, run by Git through core.hooksPath, stops a commit that names no issue

FR-027checkno test run

The controller MUST hold the module ergonex hook <pre-commit|commit-msg|pre-push>, which the generated hooks run (0003-host FR-014, FR-025): it is internal, it only reads, and its status is 0 or 1 where it ran its checker and 2 or 3 where it could not.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-render.test.ts: the commit-msg, pre-push and pre-commit hooks run ergonex hook, which only reads and ends 0 or 1 where it ran its checker, and the script turns any other status into cannot-run

FR-028checkpassing

ergonex modules --probe MUST run a module found on the PATH only with the user's confirmation for it, or with --trust, and it MUST NOT sandbox the module: a probe is the run of a program the user approved.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-probe.test.ts: modules --probe asks about each module found on the PATH (the question says it is not sandboxed) and runs only those the person says yes to, or all with --yes; with no terminal and no --yes it is a usage failure (status 2) that runs nothing; a module registered by the workspace is not asked about; ergonex-command.test.ts: the PATH modules probed with --yes

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

Tests: passed: suite/ergonex-probe.test.ts modules --probe runs a module found on the PATH only after the person says yes to it, or w

FR-029checkpassing

The five seconds of FR-008 MUST stay the default wait for --ergonex-manifest; --probe-timeout MAY raise them, and a module that does not answer in time MUST be an informational finding of the run (the module named, the wait given) and MUST NOT make the run fail or change its exit status.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-probe.test.ts: the wait is 5000 ms by default and --probe-timeout SECONDS sets another (a value that is not a whole number of at least 1 is a usage failure); a module that does not answer in time is an informational finding naming it and the wait, listed as opaque, the other modules are listed and the status stays 0; a longer wait lets a slow module answer

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

Tests: passed: suite/ergonex-probe.test.ts the wait for --ergonex-manifest is five seconds by default and --probe-timeout sets anothe

FR-030checkpassing

The tree of the program (ergonexProgram) MUST be a Headless model with no problem, and each command's action MUST say what it is: the reports (plan, status, doctor, verify, paths, tools, shell print, worktree list, modules, hook, start) only read and are safe to repeat; render, repos add, repos adopt, setup and shell install preview with --dry-run; repos delete and worktree prune are destructive, preview and are confirmed; and the program MUST ask no one a question a flag or the action's own facts can answer.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-headless.test.ts: the tree is a Headless model with no problem and a reach policy for every action, the reports only read and are safe to repeat, the previewing actions say so, and the destructive ones preview and are confirmed

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

Tests: passed: suite/ergonex-headless.test.ts the program's tree is a well-formed Headless model: no duplicate or reserved word, every a

FR-031checkpassing

Ergonex MUST keep its own domain logic (the manifest, the repositories, the plan, the onboarding, the tool catalog and the evidence) separate from the surface: nothing in src/ outside commands/ and ergonex.ts imports Headless, and no command keeps a second path (an alias, a deprecated option or a shim) for a surface that was replaced.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-boundaries.test.ts, ergonex-headless.test.ts: the domain logic is the pure core and the surface is commands/ and ergonex.ts; ergonex-headless.test.ts runs the program through Headless (log, hints, explain, envelope) and ergonex-command.test.ts proves the old words are not commands

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

Tests: passed: suite/ergonex-headless.test.ts nothing outside commands/ and ergonex.ts imports Headless, the package names it by its exp

Out of scope

  • The workspace's layout, portability, plan, policy, tools and evidence: 0002-workspace-model. The generated files, hooks, Git configuration and shell snippet: 0003-host.
  • A consent class of reach for --git-include (commons headless 0008-exit-style-consent FR-004): a non-goal by decision. The class belongs to a whole action and would demand --consent <id> of every run of setup that has no terminal, and --git-include is itself a flag a person typed after the exact change is shown, so the flag is the consent (FR-020); splitting it into a command of its own is not worth a second path.
  • ifc (commons 0008-test-evidence) and any general Mizan command: ergonex does not front them.
  • The contents of a module's own commands beyond the contract: the module's.

Edge cases

  • ergonex plna: exit status 2, and plan named, per FR-006.
  • ergonex ../x or a name with a space: refused as a usage error, not run, per FR-005.
  • A module ergonex-doctor on the PATH: the built-in doctor runs, and the hidden module is reported, per FR-004.
  • An ergonex-foo on the PATH that prints nothing for --ergonex-manifest: listed and run as an opaque command, per FR-008.
  • A registered module whose program changed since its hash was recorded: refused with exit status 3, per FR-011.
  • ergonex setup --dry-run: the plan is shown and nothing is changed, per FR-017.
  • ergonex setup on Windows without elevation: repositories get core.longpaths, the system setting is not touched and the steps are printed, per FR-019.
  • ergonex apply with a plan that holds an ergonex:InstallTool: not possible, as apply never makes one, per FR-012 and FR-017.
  • A warning and nothing else: exit status 1; an informational finding and nothing else: exit status 0, per FR-010.

Scenarios

  • Given an executable ergonex-hello on the PATH and no module of that name built in or registered, When ergonex modules runs, Then hello is listed with the source ergonex:Path, it was not run, and ergonex hello runs it (FR-003, FR-004, FR-009).
  • Given a module ergonex-hello that answers --ergonex-manifest with JSON of the contract, When ergonex modules --probe runs, Then its summary and commands are listed, and with an answer that does not decode it is listed as opaque (FR-008, FR-009).
  • Given a typo of a module name, When it is run, Then the status is 2 and the nearest names are listed (FR-006, FR-010).
  • Given a workspace with a warning, When ergonex doctor runs, Then the status is 1, and with only informational findings it is 0 (FR-010, FR-014).
  • Given any state, When ergonex setup --dry-run runs, Then it shows its plan, installs nothing and changes nothing (FR-017).
  • Given a catalog with a tool pinned for this system, When ergonex setup runs, Then the tool is in the tools folder of ergonex's data (<data>/tools/, commons 0031-install-locations), git was only probed, and an ergonex:Setup with ergonex:applied true was recorded (FR-017, FR-018).
  • Given a repository that needs no worktree, When ergonex worktree create runs, Then it says the repository's own checkout is the place and makes none (FR-016).
  • Given a Bun and a Node 26 runtime, When ergonex status runs on each, Then the report is the same (FR-024).

Assumptions

  • The model of the controller is Git's: git foo runs git-foo, found on the PATH (FR-004); Ergonex credits it (0002-workspace-model FR-046).
  • Node 26 runs the .ts sources of ergonex as they are, which strips their types (FR-024).
  • A person who wants a module on the PATH approves it by adding it to the catalog within 90 days, or by registering it with its hash (FR-011).
  • 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

  • Module - a part of the command, ergonex-<name>, with its source and summary (ergonex:Module).
  • ModuleSource - built-in, registered or on the path, in that order.
  • ExitStatus - 0 ok, 1 findings, 2 usage, 3 environment (and 4 pending, Headless').
  • Setup - the one run that may install or change the host; --dry-run shows its plan.

Success criteria

SC-001success criterion

A module written in any language can join the command by being named ergonex-<name> and answering --ergonex-manifest, and ergonex runs nothing it did not find in the order of FR-004.

SC-002success criterion

Only ergonex setup changes anything outside the workspace's own files, and it shows what it will do 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

commands/catalogue, commands/define, commands/program, doctor, findings, Ergonex, modules/external, modules/name, modules/registry, modules/types, Intellectual Frontiers Workspaces, Ergonex host: typed templates, generated files and what is managed

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