FR-001checkpassingIntellectual Frontiers Workspaces
0002Active0002-workspace-model · owner if · domain commons
The workspace
FR-002checkpassingThe 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.
FR-003checkpassingErgonex 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.
FR-004checkpassingErgonex 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).
Cited by: Ergonex host: typed templates, generated files and what is managed
FR-005nonepassingThe 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.
Layout
FR-006checkpassingA 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.
FR-007checkpassingA 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.
Cited by: The ergonex command
FR-008checkpassingPortability
FR-009checkpassingA 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.
FR-010checkpassingA 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.
FR-011checkpassingIF 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.
Cited by: Ergonex, manifest, portable, render, Ergonex host: typed templates, generated files and what is managed, Repositories
FR-012checkpassingWHILE 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.
Cited by: doctor, Ergonex, portable, types, The ergonex command
FR-013checkpassingErgonex 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).
Cited by: Ergonex host: typed templates, generated files and what is managed
FR-014checkpassingIF 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.
Git hosts
FR-015checkpassingThe 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.
FR-016checkno test runEvery 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.
FR-017checkpassingA 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.
FR-018noneno test runA 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.
FR-019checkpassingFR-020checkpassingPlan and apply
FR-021checkpassingErgonex 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.
Cited by: desired, Ergonex, plan, Ergonex host: typed templates, generated files and what is managed
FR-022checkpassingA 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.
Cited by: Ergonex, state, The ergonex command
FR-023checkpassingEvery 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.
FR-024checkpassingA 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.
FR-025checkpassingWHEN a plan has been applied and nothing has changed since, the next plan MUST hold only ergonex:Skip actions.
FR-026checkpassingFR-027checkpassingErgonex 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.
Cited by: Ergonex, plan, state, Repositories
FR-028checkpassingWHILE 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.
FR-029checkpassingFR-030checkpassingErgonex 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.
Cited by: Ergonex, plan, The ergonex command
Policy
FR-031checkpassingIF 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.
Cited by: Ergonex host: typed templates, generated files and what is managed
FR-032checkpassingWHERE 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.
FR-033checkpassingA 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.
Cited by: findings, Ergonex, policy, The ergonex command
FR-034checkpassingThe 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.
FR-035checkpassingA 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).
Cited by: findings, Ergonex, The ergonex command
FR-036checkpassingA 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.
Tools
FR-037checkpassingThe 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).
FR-038checkpassingErgonex 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.
FR-039checkpassingErgonex 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.
Cited by: Archon dialect: native-pinned, install, Intellectual Frontiers Commons, The ergonex command, Native-pinned install
FR-040checkpassingThe 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.
Evidence
FR-041checkpassingEvery 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.
Cited by: The ergonex command
FR-042checkpassingAn 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.
Cited by: plan
FR-043checkpassingWHERE 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.
Vocabulary and standards
FR-044checkno test runThe 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.
FR-045reviewno test runThe 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.
FR-046reviewno test runThe 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.
Cited by: The ergonex command, Ergonex host: typed templates, generated files and what is managed
FR-047checkno test runA 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.
FR-048checkpassingFR-049checkpassingWHERE 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.
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
Organd another whose owner isorgon the same host: both refused on every file system, per FR-011. - A repository named
conoraux.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/cin WSL: a warning fromergonex 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 planruns, Then the plan holds oneergonex:Clonefor 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 doctorruns, Then it reports an error naming the path and says thatergonex setupcan 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 doctorreports 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 doctorruns, 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,statusanddoctorbehavior: 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,bunandnodeare 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
unalignedterm 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,statusanddoctorbehavior 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 speakhttps; 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 criterionA 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 criterionA run never loses work that exists nowhere else, and every change it makes was shown in a plan first.
SC-003success criterionAn 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