IF Commons GitHub

Intellectual Frontiers Workspaces

0002Active

0002-workspace-model · owner if · domain commons

The workspace

FR-001checkpassing

The workspace MUST be one root folder, $ERGONEX_HOME, which is $HOME/workspaces where the variable is not set (%USERPROFILE%\workspaces on Windows), and which --home overrides for one run; the root is the ergonex:Workspace.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: the root of a run is --home, else $ERGONEX_HOME, else $HOME/workspaces, as a real program on Bun and Node (the pure resolution is proved in ergonex-layout.test.ts)

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

Written in: ergonex/src/layout.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-layout.test.ts the root is --home, else $ERGONEX_HOME, else $HOME/workspaces (%USERPROFILE%\workspaces on

Cited by: Ergonex, layout

FR-002checkpassing

The workspace's own area MUST be <home>/.ergonex/, holding the typed manifest workspace.ts, the generated files (*.auto.*), the state record, the evidence records (evidence/), the installed tools (tools/), the Git hooks (hooks/) and modules.auto.json; nothing else of Ergonex MAY be outside the repositories and worktrees.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: after init and apply the root holds the repositories' hosts, the generated files and the workspace's own area (the manifest, the state record, the generated files, hooks/, evidence/); the area's tools/ is made by ergonex setup --apply (ergonex-wiring.test.ts)

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

Tests: passed: suite/ergonex-apply.test.ts apply is idempotent: a second run changes no file, no configuration and no state record

FR-003checkpassing

Ergonex MUST read and write only inside the root, with these exceptions, each opt-in and each the work of ergonex setup alone (0001-ergonex FR-017, FR-020): the shell snippet block and the global Git include of 0003-host, and the Windows long-path setting of 0001-ergonex; it MUST NOT read a private key, a credential store or any file of ~/.ssh.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-scan.test.ts: resolveInside, readInside and forbiddenRead refuse an absolute path, .., a drive, a backslash, the home folder, NUL, a link that leads out of the root and any file of ~/.ssh or a credential store, and a hostile manifest is refused as a manifest; that every writer calls them is the controller's (M5)

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

Written in: ergonex/src/scan/boundary.ts, ergonex/src/scan/host/scan.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-scan.test.ts a hostile manifest cannot make Ergonex read or write outside the root: absolute paths, `..; passed: suite/ergonex-scan.test.ts a link inside the root that leads outside it is refused by the reader; passed: suite/ergonex-scan.test.ts a manifest whose paths are hostile is refused as a manifest, so that none of them is ever and 2 more

FR-004checkpassing

Ergonex MUST manage only the workspace: it MUST NOT be a dotfiles or user-profile manager, and the scope statement of ergonex is that it manages only Intellectual Frontiers Workspaces, is not a general IFC or Mizan controller and does not front ifc (0001-ergonex FR-002).

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-command.test.ts: ergonex --help says in these words that it manages only Intellectual Frontiers Workspaces and does not front ifc; ergonex-apply.test.ts and ergonex-boundaries.test.ts: no file of a user's profile is read or written

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 --help says it manages only Intellectual Frontiers Workspaces and is not an IFC or

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

FR-005nonepassing

The library, its command and its templates MUST live in commons/ergonex/ and be on rung 10 of the ladder, whose kind is environment (commons 0016-ladder FR-010); a rung below MUST NOT import it.

Enforced (none): Planned, M4 of issue #10: commons/ergonex/ exists and no rung below imports it (ergonex-boundaries.test.ts proves it); the command and the templates are M5's, and rung 10 as an instance of the ladder is the lead's amendment of 0016-ladder

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

Written in: ergonex/src/host/locations.ts, ergonex/src/places.ts, ergonex/src/platform/k-args.ts, ergonex/src/platform/k-otel.ts, ergonex/src/platform/k-test-record.ts, ergonex/src/platform/k-test-report.ts and 12 more

Tests: passed: suite/ergonex-boundaries.test.ts every file of src/ begins with a module comment, and every export has a TSDoc; passed: suite/ergonex-boundaries.test.ts the library imports commons by package name only: no import leaves the library by a relati

Layout

FR-006checkpassing

A repository MUST be at <home>/<git-host>/<path...>/<repo>, which mirrors its remote URL: the host name in lower case, then the path of the remote as the host writes it, so that GitHub gives github.com/<owner>/<repo> and GitLab gives its groups to any depth.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-layout.test.ts: a repository is at the lower-case host then the remote's path as the host writes it (GitHub owner and repository, GitLab groups to any depth), whichever spelling the remote has, and the path maps back to its remote

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

Written in: ergonex/src/types.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-layout.test.ts a repository is at the host in lower case, then the path of its remote as the host writes ; passed: suite/ergonex-layout.test.ts the path of a repository is a property of its remote: any valid remote that is accepted ma

Cited by: Ergonex, layout, manifest, types

FR-007checkpassing

A worktree MUST be at <home>/.worktrees/<git-host>/<path...>/<repo>/<branch-slug>, and Ergonex MUST create one only where another person or agent, or uncommitted work, is on the repository; otherwise the repository's own checkout is the place to work.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-layout.test.ts, ergonex-plan.test.ts: a worktree is at .worktrees/<host>/<path...>/<repo>/<branch-slug>, with the slug free of what Windows refuses, and the plan holds a CreateWorktree only where another worker or uncommitted work is on the repository

Proved by: ergonex/suite/ergonex-apply.test.ts, ergonex/suite/ergonex-layout.test.ts, ergonex/suite/ergonex-plan.test.ts

Written in: ergonex/src/host/worktrees.ts

Tests: passed: suite/ergonex-apply.test.ts worktree create makes a worktree only where someone else or uncommitted work is on the rep; passed: suite/ergonex-layout.test.ts a worktree is at `.worktrees/<git-host>/<path...>/<repo>/<branch-slug>`; passed: suite/ergonex-layout.test.ts a worktree is made only where another person or agent, or uncommitted work, is on the repo; passed: suite/ergonex-plan.test.ts a worktree is planned only where another worker or uncommitted work is on the repository

Cited by: The ergonex command

FR-008checkpassing

IF a Git host or a path segment of a remote is named like a folder of the workspace (.worktrees, .ergonex, .git), THEN Ergonex MUST refuse it and name it.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-layout.test.ts, ergonex-manifest.test.ts: a host or a segment named .worktrees, .ergonex or .git, in any case, is refused and named

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

Tests: passed: suite/ergonex-layout.test.ts a host or a path segment named like a folder of the workspace is refused, and named; passed: suite/ergonex-manifest.test.ts a remote that names a folder of the workspace or a Windows device is refused naming it

Cited by: Ergonex, layout, render

Portability

FR-009checkpassing

A path segment MUST be a PortableSegment, a branded type made only by a function that refuses: an empty segment, . and ..; the characters <, >, :, ", /, \, |, ? and * and the control characters; a name ending in a dot or a space; a Windows device name (CON, PRN, AUX, NUL, COM0 to COM9 and LPT0 to LPT9, with the superscript digits in their place) in any case and with any extension; a name longer than 255 bytes in UTF-8; and a name that is not in Unicode normalization form NFC.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-portable.test.ts: the fixture of hostile names (empty, dot, forbidden and control characters, trailing dot or space, every device name in any case with any extension and the superscript digits, over 255 bytes, non-NFC), pure so that it runs on every system

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

Written in: ergonex/src/portable.ts

Tests: passed: suite/ergonex-layout.test.ts a repository named like a Windows device is refused naming the device, whichever way the r; passed: suite/ergonex-manifest.test.ts a remote that names a folder of the workspace or a Windows device is refused naming it; passed: suite/ergonex-portable.test.ts every segment a made path holds is portable, and the path keeps `/` between them whatever ; passed: suite/ergonex-portable.test.ts a segment is refused above 255 bytes of UTF-8, counted in bytes and not in characters; passed: suite/ergonex-portable.test.ts a segment is refused for a Windows device name in any case and with any extension, supersc and 4 more

Cited by: Ergonex, portable

FR-010checkpassing

A path of the workspace MUST be a RepoPath or a path made from one, held with / between segments in data and given the native separator only where it meets the operating system.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-portable.test.ts: a path of the workspace is made only from portable segments with / between them, never absolute, never holding .. or a drive, and given the native separator only by nativePath

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

Tests: passed: suite/ergonex-portable.test.ts every segment a made path holds is portable, and the path keeps `/` between them whatever

FR-011checkpassing

IF two repositories, two worktrees or two generated files have paths that are equal after NFC and Unicode case folding, THEN Ergonex MUST refuse both, on every file system, and name both.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-portable.test.ts, ergonex-manifest.test.ts: paths equal after NFC and case folding collide, and the manifest refuses both and names each other, on every file system

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

Tests: passed: suite/ergonex-manifest.test.ts two remotes whose paths differ only in case, or in normalization, are both refused and eac; passed: suite/ergonex-portable.test.ts two paths equal after NFC and case folding collide, each naming the other, and others do n

Cited by: Ergonex, manifest, portable, render, Ergonex host: typed templates, generated files and what is managed, Repositories

FR-012checkpassing

WHILE long paths are not enabled on Windows, a path of the workspace longer than 259 characters (Windows' limit of 260 counts the terminating character) MUST be an ergonex:Error naming the path.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-portable.test.ts: 259 characters is accepted and 260 is a path-too-long error naming the path, unless long paths are enabled (the doctor message and the ergonex:Error severity are the command's, M5)

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

Written in: ergonex/src/doctor.ts, ergonex/src/setup/windows.ts

Tests: passed: suite/ergonex-portable.test.ts a Windows path of 259 characters is accepted and of 260 is an error naming the path, unles; passed: suite/ergonex-record.test.ts on Windows a path of more than 259 characters is an error naming it while long paths are o; 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

Cited by: doctor, Ergonex, portable, types, The ergonex command

FR-013checkpassing

Ergonex MUST NOT create a symbolic link and MUST NOT need one, and a file that a symbolic link served in the earlier workspace tools (the VS Code workspace files) MUST be a generated *.auto.code-workspace file (0003-host FR-005).

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-render.test.ts: a manifest of two groups gives two *.auto.code-workspace files with relative paths and no symbolic link anywhere in the root; ergonex-templates.test.ts: the template makes no symbolic link

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

Tests: passed: suite/ergonex-plan.test.ts a repository's local Git configuration is set where it differs from the manifest's, in eve; 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

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

FR-014checkpassing

IF the root is on FAT or exFAT (no execute bit, a two-second time resolution), on a network share (unreliable locks) or under WSL on a Windows drive (/mnt/c: slow, case-insensitive), THEN ergonex doctor MUST report an ergonex:Warning saying which and why, as found by a probe and never guessed from the path alone.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-record.test.ts: FAT, exFAT, a network share and a Windows drive under WSL are each classified from the type a probe reports (never from the path) and are warnings, and a probe not made is said; ergonex-render.test.ts: doctor runs the probe (stat -f on Linux, the table of mounts on macOS); the probe on Windows is not built and says so

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

Written in: ergonex/src/host/probe.ts

Tests: passed: suite/ergonex-record.test.ts FAT, exFAT, a network share and a Windows drive under WSL are each a warning found by the ; passed: suite/ergonex-render.test.ts doctor checks the runtime, the layout, the file system, the hooks and the generated files,

Cited by: doctor, Ergonex

Git hosts

FR-015checkpassing

The workspace MUST reach a Git host only through one ergonex:GitManager interface, shaped at the same time for GitHub (public and private repositories), GitLab (public and private repositories, groups to any depth) and plain Git, and the interface MUST NOT be fixed until the three adapters pass the same conformance tests.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-adapters.test.ts, githost-live.test.ts: GitHub, GitLab and plain Git pass the same conformance function (tests/githost-conformance.ts) over recorded exchanges, a loopback server and a real repository

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

Tests: passed: suite/ergonex-boundaries.test.ts every file of src/ begins with a module comment, and every export has a TSDoc

FR-016checkno test run

Every Git manager MUST offer the common capabilities: the clone URL of a repository and its path in the workspace (ergonex:CloneUrl), authentication (ergonex:Credentials), the default branch (ergonex:DefaultBranch) and whether a commit's signature verifies (ergonex:SignedCommits); and GitHub and GitLab MUST also offer protected branches (ergonex:ProtectedBranches), issues (ergonex:Issues) and pull or merge requests (ergonex:ChangeRequests) behind the same calls.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-ontology.test.ts: the kinds Github, Gitlab and Git each support the four common capabilities, and GitHub and GitLab protected branches, issues and change requests

FR-017checkpassing

A capability that a Git manager's kind does not list (ergonex:supports) MUST be answered with a typed result that says it is unsupported, naming the manager and the capability, and MUST NOT be silently skipped, emulated or thrown: GitLab alone offers groups to any depth (ergonex:NestedGroups), and plain Git offers no protected branches, issues or change requests.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-adapters.test.ts, githost-remote.test.ts: a capability a kind lacks is a typed unsupported result naming the host and the capability (GitHub nested groups, plain Git protected branches, issues and change requests), and the table is the ontology's

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

Tests: passed: suite/ergonex-layout.test.ts a path deeper than the manager offers is refused naming the manager and the path, and GitL

FR-018noneno test run

A Git manager MUST authenticate through a Git credential helper, through the host's own command-line tool (gh, glab) or through a token read from the environment, and Ergonex MUST NOT write a credential into any file, a remote URL or the evidence.

Enforced (none): Planned, M4 of issue #10: the adapters read a token only from the environment they are handed, send it to the one host they serve, and hold it in no result, URL or file (githost-live.test.ts, githost-remote.test.ts, ergonex-boundaries.test.ts); the host's own command-line tools (gh, glab) and the evidence's lack of a credential are not wired

FR-019checkpassing

The kind of manager for a remote MUST be GitHub for github.com, GitLab for gitlab.com and for a host the manifest names as GitLab, and plain Git for every other host; a self-hosted GitLab MUST be named in the manifest and MUST NOT be guessed from a URL.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-remote.test.ts, ergonex-manifest.test.ts: GitHub for github.com, GitLab for gitlab.com and the hosts the manifest names, plain Git for every other, and a self-hosted GitLab is never guessed from a URL

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

Tests: passed: suite/ergonex-manifest.test.ts a path deeper than the manager offers is refused, and a self-managed GitLab is the manifes

Cited by: Ergonex, layout, manifest

FR-020checkpassing

A repository whose path is deeper than its manager supports (more than two segments on a host without ergonex:NestedGroups) MUST be refused with the manager and the path named.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-layout.test.ts, ergonex-manifest.test.ts: a path of more than two segments on a host without nested groups is refused naming the manager and the path, and GitLab takes any depth

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

Tests: passed: suite/ergonex-layout.test.ts a path deeper than the manager offers is refused naming the manager and the path, and GitL; passed: suite/ergonex-manifest.test.ts a path deeper than the manager offers is refused, and a self-managed GitLab is the manifes

Cited by: Ergonex, layout, manifest

Plan and apply

FR-021checkpassing

Ergonex MUST be a plan and an apply: plan(desired, observed) MUST be a pure function from the manifest and the observed state to an ergonex:Plan, an ordered list of ergonex:Actions, and MUST NOT read or write anything itself; the plan is a plan in the sense of PROV-O.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-plan.test.ts, ergonex-boundaries.test.ts: plan(desired, observed) is a pure function (arguments frozen, same plan and digest, the pure core imports no clock, environment or file)

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

Written in: ergonex/src/desired.ts, ergonex/src/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-boundaries.test.ts the pure core imports only the kernel, itself and the Git host's types, and reads no clock; passed: suite/ergonex-plan.test.ts a missing repository is one Clone at the path that mirrors its remote, and the plan change; passed: suite/ergonex-plan.test.ts plan is a pure function: it does not change its arguments, and the same arguments give the

Cited by: desired, Ergonex, plan, Ergonex host: typed templates, generated files and what is managed

FR-022checkpassing

A repository MUST be observed as exactly one ergonex:RepoState (ergonex:Missing, ergonex:Clean, ergonex:Dirty, ergonex:Ahead, ergonex:Behind, ergonex:Diverged, ergonex:Locked, ergonex:Detached, ergonex:WrongRemote or ergonex:NotARepo), and the plan's action for it MUST be the state's ergonex:defaultAction: clone where it is missing, fast-forward where it is behind, refuse where it is on the wrong remote or not a repository, and skip, with the reason, in every other state.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-plan.test.ts, ergonex-state.test.ts: each of the ten states is observed in a real repository and the plan's action for it is the state's defaultAction in the ontology

Proved by: ergonex/suite/ergonex-apply.test.ts, ergonex/suite/ergonex-plan.test.ts, ergonex/suite/ergonex-state.test.ts

Written in: ergonex/src/host/apply.ts, ergonex/src/host/observe.ts, ergonex/src/state.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 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, ; passed: suite/ergonex-plan.test.ts a dirty repository whose remote moved on is skipped with the reason, never fast-forwarded and 4 more

Cited by: Ergonex, state, The ergonex command

FR-023checkpassing

Every action MUST be of one ergonex:ActionKind: ergonex:Clone, ergonex:FastForward, ergonex:CreateWorktree, ergonex:ConfigureRepo, ergonex:ConfigureHost, ergonex:WriteGenerated, ergonex:RemoveGenerated, ergonex:InstallTool, ergonex:Skip or ergonex:Refuse, and a switch over them MUST be exhaustive.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-ontology.test.ts: the ten action kinds are the code list the specification names; the exhaustive switch over them is the compiler's

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

Tests: passed: suite/ergonex-plan.test.ts the ten kinds of action are the ontology's, with its destructive and host-change flags, an

FR-024checkpassing

A plan MUST change nothing, and apply MUST observe a repository again before each action on it and MUST NOT carry out an action whose observed state differs from the plan's, reporting it as skipped.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: apply observes each repository again before each action and reports as skipped an action whose state changed; the plan changes nothing

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

Tests: passed: suite/ergonex-apply.test.ts a plan clones the missing repository at the path that mirrors its URL and changes nothing;

FR-025checkpassing

WHEN a plan has been applied and nothing has changed since, the next plan MUST hold only ergonex:Skip actions.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: after apply the next plan holds only skips and a second apply changes no file, configuration or state record

Proved by: ergonex/suite/ergonex-apply.test.ts, ergonex/suite/ergonex-plan.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-plan.test.ts a plan whose every action is a skip changes nothing

FR-026checkpassing

The workspace MUST update a repository by fast-forward only: Ergonex MUST NOT rebase, reset, merge, force or discard, and the plan MUST hold an ergonex:FastForward only for a state that is ergonex:fastForwardable, which is ergonex:Behind alone.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-plan.test.ts, ergonex-state.test.ts: a FastForward is planned for Behind and for no other state (a property over every state), and a dirty repository behind its remote is skipped

Proved by: ergonex/suite/ergonex-apply.test.ts, ergonex/suite/ergonex-plan.test.ts, ergonex/suite/ergonex-state.test.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 repository that is behind is fast-forwarded by apply, status shows it before and after, ; passed: suite/ergonex-plan.test.ts a dirty repository whose remote moved on is skipped with the reason, never fast-forwarded; passed: suite/ergonex-plan.test.ts a fast-forward is planned for a repository that is behind and for no other state, and no a; passed: suite/ergonex-state.test.ts the plan made from real repositories holds the default action of each, and a dirty reposit

Cited by: Ergonex, state

FR-027checkpassing

Ergonex MUST NOT delete a folder whose state ergonex:holdsLocalWork (every state but ergonex:Missing, ergonex:Clean and ergonex:Behind), nor a worktree with unpushed commits or uncommitted changes, nor a generated file whose bytes are not the ones the state record holds.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: a dirty, ahead, diverged or locked repository is never touched, a non-repository folder and another remote's clone are never overwritten, a generated file edited by hand is never removed, and a worktree with work is never pruned

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

Tests: passed: suite/ergonex-apply.test.ts worktree create makes a worktree only where someone else or uncommitted work is on the rep; 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 Git lock file makes the repository locked: it is not acted on, the lock is not removed, ; passed: suite/ergonex-apply.test.ts a generated file that is no longer generated is removed only with --allow-destructive and and 2 more

Cited by: Ergonex, plan, state, Repositories

FR-028checkpassing

WHILE a Git lock file is present in a repository, the repository MUST be ergonex:Locked and Ergonex MUST NOT act on it or remove the lock; two runs of ergonex on one workspace MUST NOT write at once, the second waiting or refusing with the first named.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: a Git lock file makes the repository Locked, which apply does not act on and whose lock it does not remove; a second run refuses with the first named, and a lock whose holder is gone is taken over

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

Tests: passed: suite/ergonex-apply.test.ts a Git lock file makes the repository locked: it is not acted on, the lock is not removed, ; passed: suite/ergonex-apply.test.ts two runs of ergonex on one workspace do not write at once: the second refuses, naming the ; passed: suite/ergonex-state.test.ts a lock file makes the repository Locked, and observing it does not remove the lock; passed: suite/ergonex-wiring.test.ts setup and apply take the same lock file of the workspace: while another run holds it, setu

FR-029checkpassing

An action of a kind that is ergonex:destructive MUST appear in the plan and MUST NOT be carried out unless the run says --allow-destructive; without it the action is reported as skipped.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-apply.test.ts: RemoveGenerated is in the plan and is carried out only with --allow-destructive and only while the file is as written

Proved by: ergonex/suite/ergonex-apply.test.ts, ergonex/suite/ergonex-plan.test.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-plan.test.ts the ten kinds of action are the ontology's, with its destructive and host-change flags, an

Cited by: Ergonex, plan

FR-030checkpassing

Ergonex MUST NOT carry out an action of a kind with ergonex:hostChange (ergonex:InstallTool, ergonex:ConfigureHost) in any run but ergonex setup (0001-ergonex FR-017), and a plan made by any other command MUST NOT hold one.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-setup.test.ts: stepChangesHost is true for exactly InstallTool, SetSystemLongPaths and AddGitInclude, setup carries them out only where --apply is given (a dry run, with --git-include too, changes nothing), and ergonex tools has no install argument (ergonex-tools.test.ts); the plan of every other command holds none by plan.ts (ergonex-plan.test.ts); ergonex-wiring.test.ts: run as a real program, no plan of plan or apply holds an install, a dry run of setup fetches and writes nothing, and only setup --apply installs

Proved by: ergonex/suite/ergonex-apply.test.ts, ergonex/suite/ergonex-plan.test.ts, ergonex/suite/ergonex-setup.test.ts, ergonex/suite/ergonex-tools.test.ts, ergonex/suite/ergonex-wiring.test.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-plan.test.ts the ten kinds of action are the ontology's, with its destructive and host-change flags, an; 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 and 1 more

Cited by: Ergonex, plan, The ergonex command

Policy

FR-031checkpassing

IF a managed file or setting holds a plaintext token (a personal access token of GitHub or GitLab, a password in a remote URL, an authorization header), THEN Ergonex MUST report an ergonex:Error naming the file and the line and MUST NOT print the secret; the scan MUST run on the generated files, the manifest and the local Git configuration of each repository, and no run is without it.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-scan.test.ts: tokens of GitHub and GitLab, private key blocks, a credential in a URL and authorization headers are errors naming the file and the line and never the secret, placeholders are not secrets, and the generated files, the manifest and each repository's local Git configuration are scanned inside the root; running the scan in every command is the controller's (M5); ergonex-wiring.test.ts: ergonex doctor finds a token in a repository's local Git configuration and in the manifest, naming the file and line and never printing it (nor holding it in a record), and the pre-commit hook stops a commit that stages one

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

Written in: ergonex/src/host/staged.ts, ergonex/src/scan/secrets.ts

Tests: passed: suite/ergonex-scan.test.ts a finding is an error naming the file and the line, and never holds the secret, not a char; passed: suite/ergonex-scan.test.ts a placeholder, an environment reference or an ordinary URL is not a secret; passed: suite/ergonex-scan.test.ts the scan finds GitHub and GitLab tokens, private key blocks, a credential in a URL and an ; passed: suite/ergonex-scan.test.ts the scan reads the generated files, the manifest and each repository's local Git configura; passed: suite/ergonex-wiring.test.ts doctor finds a plaintext token in a repository's local Git configuration as an error that and 1 more

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

FR-032checkpassing

WHERE the manifest names a regulated domain (ergonex:regulatedDomain), the policy MUST require signed commits (ergonex:requiresSignedCommits, OpenPGP or SSH), a commit in a managed repository that is not signed and verified MUST be an ergonex:Error, and the Git hooks MUST fail where they cannot check; elsewhere the same commit MUST be an ergonex:Warning.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-scan.test.ts: signedCommitFindings is an error where a regulated domain is named and a warning elsewhere, over the signature letters of real commits from real git (N unsigned, G signed with an SSH key made by ssh-keygen); the Git hooks that fail where they cannot check are M5's templates; ergonex-wiring.test.ts: ergonex doctor reports an unsigned commit of a managed repository as a warning, and as an error once the manifest names a regulated domain

Proved by: ergonex/suite/ergonex-findings.test.ts, ergonex/suite/ergonex-manifest.test.ts, ergonex/suite/ergonex-render.test.ts, ergonex/suite/ergonex-scan.test.ts, ergonex/suite/ergonex-wiring.test.ts

Written in: ergonex/src/policy.ts, ergonex/src/scan/policy-scans.ts

Tests: passed: suite/ergonex-findings.test.ts an unsigned commit is an error where a regulated domain is named, a warning elsewhere, and; passed: suite/ergonex-manifest.test.ts a regulated domain makes the policy require signed commits, and the policy limits the host; 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 a hook that cannot run its checker (no bun, no node, no ergonex) fails with the reason whe; passed: suite/ergonex-scan.test.ts a commit signed with an SSH key is read as G, and the same repository's unsigned commit st and 3 more

Cited by: Ergonex, policy

FR-033checkpassing

A tool or an ergonex-* module that is not in the catalog MUST be an ergonex:Informational finding from the day it is first seen and an ergonex:Warning once it is more than ergonex:unapprovedGraceDays (90) days old, the day recorded in the state record and never restarted by a later run.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-tools.test.ts, ergonex-scan.test.ts: a tool or an ergonex-* module outside the catalog is informational through day 90 and a warning from day 91, the day first seen kept by firstSeen; writing the day into the state record is the controller's (M5); ergonex-wiring.test.ts: ergonex doctor, with a real ergonex-* executable on the PATH, reports it informational from the first day and at 89 days and a warning at 91, writes the first-seen day to state.auto.json and never restarts it, and a catalog tool that provides it ends the finding; ergonex tools does the same for a folder of tools the catalog does not list

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

Written in: ergonex/src/findings.ts, ergonex/src/host/seen.ts

Tests: passed: suite/ergonex-findings.test.ts a tool outside the catalog is informational for 90 days and a warning after: 89 days ago i; passed: suite/ergonex-findings.test.ts the day first seen is never restarted by a later run; 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-tools.test.ts a tool outside the catalog is informational for 90 days from the day first seen and a warn and 2 more

Cited by: findings, Ergonex, policy, The ergonex command

FR-034checkpassing

The rules of branches and commits MUST be those of the IFCCM (commons 0020-ifccm): every commit names an issue and a worktree's branch is named for its issue, and the workspace's hooks and ergonex worktree MUST apply them without a rule of their own.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-render.test.ts: the commit-msg hook, run by Git through core.hooksPath, applies the commit rules of 0020-ifccm (mizan/changes/commit-message.ts); ergonex-apply.test.ts: ergonex worktree create names the issue in the branch (branchNamesIssue is the one place that says how, until 0020-ifccm does)

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

Tests: passed: suite/ergonex-apply.test.ts worktree create makes a worktree only where someone else or uncommitted work is on the rep; passed: suite/ergonex-render.test.ts the commit-msg hook, run by Git through core.hooksPath, stops a commit that names no issue

FR-035checkpassing

A finding MUST be an ergonex:Finding with a rule identifier, an ergonex:Severity (ergonex:Informational, ergonex:Warning or ergonex:Error), a message, what it is about and the day it was first seen, and every command MUST be able to write its findings as a SARIF 2.1.0 log whose results have the level of the severity's ergonex:sarifLevel (note, warning, error).

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-findings.test.ts: the finding type, its severities and their SARIF levels (the ontology's), the SARIF 2.1.0 log of findings and the exit status they give

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

Tests: passed: suite/ergonex-findings.test.ts findings are written as a SARIF 2.1.0 log whose results have the level of the severity, an; passed: suite/ergonex-findings.test.ts the exit status of a run is Findings for a warning or an error and Ok for none or informat; passed: suite/ergonex-findings.test.ts the severities and their SARIF levels are the ontology's; passed: suite/ergonex-render.test.ts doctor checks the runtime, the layout, the file system, the hooks and the generated files,

Cited by: findings, Ergonex, The ergonex command

FR-036checkpassing

A message of ergonex doctor MUST state what is wrong and what to do: that Windows long paths are not enabled is a message of ergonex doctor (an ergonex:Informational finding while no path exceeds the limit of FR-012, an ergonex:Error once one does) and it MUST name ergonex setup as the way.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-record.test.ts: a path of 270 characters is an error naming it with ergonex setup as the way, and that Windows long paths are not enabled is informational while none exceeds the limit; ergonex-render.test.ts: each doctor check is ok, suggest, warn or error with what to do

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

Tests: passed: suite/ergonex-record.test.ts on Windows a path of more than 259 characters is an error naming it while long paths are o; passed: suite/ergonex-render.test.ts doctor checks the runtime, the layout, the file system, the hooks and the generated files,; 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

Cited by: doctor, Ergonex

Tools

FR-037checkpassing

The tool catalog (ergonex:ToolCatalog) MUST be in the manifest and MUST hold, for each ergonex:Tool, its name, one pinned version (never latest and never a range), what it provides and, for each operating system and architecture, an https URL and a SHA-256; WHERE the environment sets ERGONEX_ALLOW_LOOPBACK_HTTP=1, an http URL to the loopback interface MAY be pinned too (the SHA-256 is still checked), every command that honors the switch MUST write on standard error the one line ergonex: ERGONEX_ALLOW_LOOPBACK_HTTP is set: http to the loopback interface is accepted (the SHA-256 is still checked), and the report of the run MUST hold a finding of severity informational (ergonex/loopback-http).

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-tools.test.ts: decodeCatalog holds name, one pinned version, provides and per system and architecture an https URL and a SHA-256, and refuses latest, a range, http, a credential in a URL, a bad hash and a path that leaves the folder; adding the field to the manifest decoder is the lead's; ergonex-wiring.test.ts: the catalog is the manifest's optional tools field, decoded with the manifest, and its tools are in tools.auto.json; ergonex-loopback.test.ts: while ERGONEX_ALLOW_LOOPBACK_HTTP is set ergonex writes the one line on standard error and the report holds the informational finding ergonex/loopback-http, on Bun and Node 26, with the same exit status

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

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

Tests: passed: suite/ergonex-layout.test.ts a pinned version is major.minor.patch, never latest and never a range; passed: suite/ergonex-loopback.test.ts ergonex says so once on standard error and puts an informational finding in the report whi; passed: suite/ergonex-loopback.test.ts the switch is on only where the environment says 1, and its line and finding are the ones ; passed: suite/ergonex-tools.test.ts the catalog refuses latest, a range, an http URL, a credential in a URL, a hash that is no; passed: suite/ergonex-tools.test.ts the catalog holds each tool's name, one pinned version, what it provides and, per system a and 1 more

Cited by: Ergonex, manifest, types

FR-038checkpassing

Ergonex MUST verify git, bun and node by a probe of their versions and MUST NOT install them; Bun is the default runtime, Node 26 the backup, and Deno is not a runtime of Ergonex.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-tools.test.ts: the probes of git, bun and node judge the version the real program says (missing, too old, unreadable, ok), the catalog refuses them as tools, and setup only probes

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

Written in: ergonex/src/tools/host/probe.ts, ergonex/src/tools/probe.ts

Tests: passed: suite/ergonex-tools.test.ts a probe judges what a tool said of its version: enough, too old, missing, or not a version; passed: suite/ergonex-tools.test.ts git, bun and node are only probed, never installed: the catalog refuses them as tools; passed: suite/ergonex-tools.test.ts the real probes run the real programs, and a program that is not there is a missing probe,

FR-039checkpassing

Ergonex MUST install a tool only from a pinned artifact of the catalog, into <data>/tools/<name>/<version>/ (the tools folder of the data folder of commons 0031-install-locations: $XDG_DATA_HOME/ergonex or ~/.local/share/ergonex, and %LOCALAPPDATA%\ergonex on Windows), with the shims of its commands in ~/.local/bin (on Windows, <data>/tools/bin), after the SHA-256 of the downloaded bytes equals the pin, and MUST refuse, writing nothing, an artifact whose hash differs.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-tools.test.ts, ergonex-setup.test.ts: the pinned artifact is fetched through the transport from a real loopback server (tar.gz, zip, bare file) and from a recorded exchange, the SHA-256 is checked before anything is written, a hash that differs writes nothing, latest and http pins are refused, and an installed tool is verified against its install record; ergonex-wiring.test.ts: setup --apply, run as a real program, fetches the pinned artifact from a loopback server and installs it, and with a hash that differs writes nothing

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

Written in: ergonex/src/tools/host/install.ts, ergonex/src/tools/install.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-tools.test.ts the catalog refuses latest, a range, an http URL, a credential in a URL, a hash that is no; 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-tools.test.ts ergonex tools verify finds a file changed, removed or added since the install, and reports and 8 more

Cited by: Archon dialect: native-pinned, install, Intellectual Frontiers Commons, The ergonex command, Native-pinned install

FR-040checkpassing

The catalog MUST be expressible as OSCAL inventory-items and the inventory of what is installed as SPDX and as CycloneDX, so that the workspace's configuration and its tools can be given to an assessor in those forms.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-tools.test.ts: the catalog as OSCAL inventory-items and what is installed as SPDX 2.3 and CycloneDX 1.6, deterministic, each with the pinned SHA-256

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

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

Tests: passed: suite/ergonex-tools.test.ts the catalog is OSCAL inventory-items and what is installed is SPDX 2.3 and CycloneDX 1.6,

Evidence

FR-041checkpassing

Every run of every command MUST write one evidence record under <state>/evidence/ (the state folder of commons 0031-install-locations: $XDG_STATE_HOME/ergonex or ~/.local/state/ergonex, and %LOCALAPPDATA%\ergonex\state on Windows), in the shape of an IFQS test record (commons 0021-ifqs), named by the run's UTC time and identifier, never overwritten; a check that did not run is recorded as not_run with its reason.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-setup.test.ts: writeRunEvidence writes one record in the IFQS test-record shape named by the UTC time and run id under .ergonex/evidence/, never overwriting, with not_run and its reason for a check that did not run; calling it at the end of every command is the controller's (M5)

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

Written in: ergonex/src/host/evidence.ts, ergonex/src/setup/evidence.ts, ergonex/src/setup/host/evidence.ts

Tests: passed: suite/ergonex-apply.test.ts every apply and plan wrote exactly one evidence record each; 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-setup.test.ts a run's evidence is one record in the IFQS shape under .ergonex/evidence/, naming the comm; passed: suite/ergonex-setup.test.ts a check that did not run is recorded as not_run with its reason, never as a pass

Cited by: The ergonex command

FR-042checkpassing

An evidence record MUST name the command and its options, the plan's hash, the version of each tool probed or installed, the state record's hash, the findings and the exit status, and MUST NOT hold a credential or the content of a file.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-setup.test.ts: the record names the command and only the names of its options, the plan hash, the state hash, the tool versions, the findings and the exit, and a record that would hold a credential is redacted or refused

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

Tests: 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-setup.test.ts a run's evidence is one record in the IFQS shape under .ergonex/evidence/, naming the comm

Cited by: plan

FR-043checkpassing

WHERE the manifest names a regulated domain, the evidence of a run MUST name the version of every tool it used, so that the validation of the software used in the quality system, which 21 CFR Part 820 (the QMSR, incorporating ISO 13485:2016) requires and the FDA's Computer Software Assurance guidance describes, can cite it. Authority: mzid:authority-21-cfr-820.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-setup.test.ts: the tool versions of the run are cases of the record and missingToolVersions names what a regulated run still lacks; passing every tool used is the controller's (M5)

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

Tests: 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-setup.test.ts where a regulated domain is named the evidence must name the version of every tool used, a

Vocabulary and standards

FR-044checkno test run

The terms of this specification MUST be the typed ontology commons/ontology/ergonex/ (prefix ergonex:), whose every class and code-list class has an audit record of the standard it rests on, or of why none does (commons 0018-standards-first FR-003 to FR-005), and whose code lists hold the keys named in this specification.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-ontology.test.ts: every class and code-list class has one audit record and the audit's rules find nothing; the three specifications name only terms the ontology defines

FR-045reviewno test run

The workspace MUST support the controls CM-2, CM-3, CM-5, CM-6, CM-7, CM-8, CM-10, SA-10, SI-7 and IA-5 of NIST SP 800-53 (and the FedRAMP baselines that select them), and the section Standards and controls MUST name, for each, the requirement of this or of a sibling specification that supports it.

Enforced (review): 0002-workspace-model FR-045 — A reviewer checks that each control of the section Standards and controls names a requirement that supports it; the OSCAL slice of NIST SP 800-53 will make the mapping data

FR-046reviewno test run

The workspace's documentation MUST credit the author of the earlier workspace tools, whose layout, ensure, status and doctor ideas and code it carries on, and chezmoi (inspiration for the source and target state, templates over data, apply, diff, status, verify and a state record, with no chezmoi code or program used), and MUST name Git's git-foo convention as the model of its modules.

Enforced (review): 0002-workspace-model FR-046 — A reviewer checks that the workspace's documentation carries the credits (the author of the earlier tools, chezmoi, Git); CREDITS.md is in commons/ergonex/

Written in: ergonex/src/ergonex.ts

Cited by: The ergonex command, Ergonex host: typed templates, generated files and what is managed

FR-047checkno test run

A remote's identity MUST be its host name (lower case, with no port) and its path, so that the HTTPS, git://, ssh:// and scp-like spellings of one remote name one repository and one path of the workspace; and a credential written into a remote URL (https://user:token@host/...) MUST be dropped on reading it and MUST NOT appear in any result, state, finding or message.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-remote.test.ts, ergonex-state.test.ts: https, ssh, scp-like and git forms of one remote are one repository, and a credential in a remote URL is dropped and in no result, error, state or finding

FR-048checkpassing

A repository's own path under the workspace root MUST be an ergonex:Informational finding where it is longer than 150 characters, which leaves room for the files inside it, and an ergonex:Error where it is longer than 259 characters, whether or not long paths are enabled.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-path-room.test.ts: a repository's path (the root and its path, as the system writes it) of up to 150 characters has no finding, over 150 is informational (ergonex/repo-path-room) and over 259 an error (ergonex/repo-path-too-long) on Windows and elsewhere whatever the long-path setting; ergonex doctor run as a program reports both and says nothing of a short path

Proved by: ergonex/suite/ergonex-path-room.test.ts

Tests: passed: suite/ergonex-path-room.test.ts a repository's path of up to 150 characters has no finding, over 150 is informational and ; passed: suite/ergonex-path-room.test.ts ergonex doctor, run as a program, reports a repository whose path leaves little room as in

Cited by: doctor, portable

FR-049checkpassing

WHERE the manifest names a regulated domain, the policy MAY waive the signed-commit rule of FR-032 for a bot account that signs through the host (GitHub's web-flow key, for one), and only under a Decision that names the account and the key; the Decision is an entry of the same harness record file that commons 0020-ifccm FR-033 reads, and no account or key without one is waived. The Decision names them in its covers as signing-waiver <account> <key> (the committer's address and the key's fingerprint or id as Git reports them), the record is the one at the root of the repository whose commits are waived, and a waived commit MUST NOT be silent: it is an ergonex:Informational finding that names the Decision, the account and the key.

Enforced (check): .github: cd commons/ergonex && bun test suite/ — ergonex-signing-waiver.test.ts: a Decision of the repository's record (signing-waiver ACCOUNT KEY in covers) clears the unsigned-commit finding only for that committer with that key, as an informational finding that names the Decision, the account and the key; another account, another key, no signature, a bad or revoked one, another repository, no regulated domain and a record that cannot be read waive nothing; facts read from real SSH-signed commits and ergonex doctor run as a program

Proved by: ergonex/suite/ergonex-signing-waiver.test.ts

Written in: ergonex/src/scan/host/waivers.ts

Tests: passed: suite/ergonex-signing-waiver.test.ts a waiver clears the finding only for the named account with the named key, says so, and le; passed: suite/ergonex-signing-waiver.test.ts ergonex doctor, run as a program, reports the waived commit as informational and the unwai; passed: suite/ergonex-signing-waiver.test.ts the Decisions of the record make waivers only where they name an account and a key; passed: suite/ergonex-signing-waiver.test.ts the facts are read from real commits and the record of the repository: a commit signed by

Cited by: changes/declaration

Out of scope

  • The command, its modules and exit codes: 0001-ergonex. The generated files, the hooks, the Git configuration and the shell snippet: 0003-host.
  • The rules of branches and commits: commons 0020-ifccm. The shape of a test record: commons 0021-ifqs.
  • A user's profile: the global Git configuration, shell start-up files, SSH keys, editor settings and credential stores are not the workspace's.

Standards and controls

  • CM-2 Baseline Configuration: the manifest and its generated files (FR-002; 0003-host FR-001, FR-009).
  • CM-3 Configuration Change Control: the plan before the apply and its evidence (FR-021, FR-024, FR-041).
  • CM-5 Access Restrictions for Change: fast-forward only, protected branches and signed commits (FR-016, FR-026, FR-032).
  • CM-6 Configuration Settings: the local Git configuration and the hooks path (0003-host FR-013).
  • CM-7 Least Functionality: the tool catalog and the unapproved-tool finding (FR-033, FR-037).
  • CM-8 System Component Inventory: the catalog and the inventory of what is installed (FR-037, FR-040).
  • CM-10 Software Usage Restrictions: pinned versions and hashes, and no tool outside the catalog after 90 days (FR-033, FR-039).
  • SA-10 Developer Configuration Management: the layout, the state of every repository, the issue named by every commit (FR-006, FR-022, FR-034).
  • SI-7 Software, Firmware, and Information Integrity: the SHA-256 of every installed tool and generated file, and ergonex verify (FR-039; 0003-host FR-010).
  • IA-5 Authenticator Management: no credential in a file, and the plaintext-token scan (FR-018, FR-031).
  • Also: FedRAMP baselines (which select these controls), the FDA's QMSR and Computer Software Assurance for software tools (FR-043), IEC 62304 (software configuration management), SLSA and OpenSSF Scorecard (source control and signed commits as practices), Git's signing formats (OpenPGP and SSH), SARIF 2.1.0 for findings (FR-035), OSCAL inventory-item, SPDX and CycloneDX for the tool inventory (FR-040) and PROV-O's Plan for a plan (FR-021).

Edge cases

  • A remote whose owner is Org and another whose owner is org on the same host: both refused on every file system, per FR-011.
  • A repository named con or aux.git: refused with the Windows device name named, per FR-009.
  • A branch whose name ends in a dot or holds a colon: its slug has neither, or the worktree is refused, per FR-009.
  • A repository in a GitLab subgroup three levels deep: cloned at that path, per FR-006 and FR-020; the same path on GitHub: refused, per FR-020.
  • A repository with uncommitted changes and a remote that moved on: skipped with the reason, never fast-forwarded, per FR-022 and FR-026.
  • A repository whose folder holds another remote's clone: refused, never overwritten, per FR-022 and FR-027.
  • A stale index.lock: the repository is locked, Ergonex does not remove the lock, per FR-028.
  • A workspace under /mnt/c in WSL: a warning from ergonex doctor, per FR-014.
  • A token pasted into a remote URL of the local Git configuration: an error naming the file and not the token, per FR-031.
  • A tool found on the path that the catalog does not list: informational for 90 days, then a warning, per FR-033.
  • A downloaded artifact whose hash is not the pin: refused and nothing written, per FR-039.

Scenarios

  • Given a workspace whose manifest names a repository that is not on disk, When ergonex plan runs, Then the plan holds one ergonex:Clone for it at the path that mirrors its remote and nothing has changed (FR-006, FR-021, FR-022, FR-024).
  • Given a repository that is behind its remote and has no local change, When the plan is applied, Then the branch is fast-forwarded and a second plan holds only skips (FR-022, FR-025, FR-026).
  • Given a repository with an uncommitted change, When its remote has new commits and the plan is applied, Then the repository is skipped with its reason and nothing in it is touched (FR-022, FR-026, FR-027).
  • Given two remotes whose paths differ only in case, When the manifest is decoded, Then both are refused and named, on every file system (FR-011).
  • Given a Windows workspace with long paths off and a repository whose path is 270 characters long, When ergonex doctor runs, Then it reports an error naming the path and says that ergonex setup can turn long paths on (FR-012, FR-036).
  • Given a GitHub manager, When nested groups are asked for, Then the answer is that they are unsupported, naming GitHub and the capability (FR-017).
  • Given a manifest that names a regulated domain, When a commit that is not signed is in a managed repository, Then ergonex doctor reports an error, and where no domain is named it reports a warning (FR-032).
  • Given a tool on the path that the catalog does not list, first seen 91 days ago, When ergonex doctor runs, Then it reports a warning, and 89 days ago it reported an informational finding (FR-033).
  • Given any command, When it ends, Then one evidence record is in the state folder (<state>/evidence/) and holds no credential (FR-041, FR-042).

Assumptions

  • The earlier workspace tools, kept private, are the origin of the layout and of the ensure, status and doctor behavior: their author is credited in the workspace's own documentation (FR-046), and nothing about them is in this repository but this credit.
  • chezmoi (Tom Payne and contributors, MIT license) is credited as inspiration for ideas only; Ergonex never calls it or depends on it (FR-046).
  • git, bun and node are the user's own: Ergonex verifies them and tells how to install them (FR-038).
  • Pinned artifacts for each operating system and architecture are published by their projects with a checksum Ergonex can pin (FR-039).
  • The Decision records that justify each unaligned term of the ontology (commons 0018-standards-first FR-005) were written on 2026-11-17 (owner decision, issue #10): every one keeps the term unaligned and is reviewed again by 2027-02-15.
  • The owner decided on 2026-11-17 to pull the layout and the ensure, status and doctor behavior of the earlier workspace tools up into Ergonex; the record is the first file of the decisions folder (commons/spec-kit/decisions/, the workspace tools pull-up).
  • This specification is Active from 2026-11-17: the requirements it does not yet prove say so in the enforcement register.
  • ERGONEX_ALLOW_LOOPBACK_HTTP (FR-037) is a stopgap, kept for a person's own local mirror and for the tests' own servers, until a test certificate authority lets those servers speak https; it is then removed. It is never on by default, and it is never silent.

Open questions

None.

Key entities

  • Workspace - the root and everything under it (ergonex:Workspace).
  • Repository, Worktree - a clone at the path that mirrors its remote, and a worktree of it for one branch.
  • GitManager - the one interface to GitHub, GitLab or plain Git.
  • Plan, Action - the ordered steps that bring the workspace to its manifest; each step has a kind.
  • Finding - what a check reports, with a severity.
  • Tool, ToolCatalog - the pinned programs the workspace approves.
  • WorkspacePolicy - what the workspace requires of itself.

Success criteria

SC-001success criterion

A person and an agent on Linux, macOS and Windows get the same layout from the same manifest, and a path that would break on one of them is refused on all.

SC-002success criterion

A run never loses work that exists nowhere else, and every change it makes was shown in a plan first.

SC-003success criterion

An assessor can read from the evidence records which tools, at which versions, were used on which day.

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

Archon dialect: native-pinned, install, desired, doctor, findings, Ergonex, layout, manifest, plan, policy, portable, render, state, types, changes/declaration, Intellectual Frontiers Commons, The ergonex command, Native-pinned install, Ergonex host: typed templates, generated files and what is managed, Repositories

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