These are the words Forge's docs, agent prompts and dashboard use for projects with several repos, components, backing services, environments and releases. Terms marked planned describe work in the named milestone and have no config key yet.
Planned in M004, except where a config key exists today.
| Term | Meaning | Config key |
|---|---|---|
| project | One or more repos Forge works on together, configured from the root repo's .forge/, with nothing outside those repos but the machine index (today's block describes a project of one repo). |
project |
| machine index | The machine's list of registered projects (forge project add|remove|list), the machine settings (forge project settings: the machine cap), the machine dashboard's runtime record (dashboard.json) and login file (dashboard-login.json), and its runtime/ dir (the login service's log and uptime.json, the sleep assertion and last restart), in ~/.forge/ or FORGE_HOME. It never holds project policy, commands or secrets, which stay in each project's .forge/. |
- |
| machine dashboard | The one forge dash server per machine: it serves every project in the machine index, each with its own pool, under /api/p/<project>/. The global pages (the Overview at #/overview, Machine at #/machine) keep the selected project, and a project's pages live at #/p/<project>/<view>; the selected project is remembered across restarts and dropped at load once it is no longer registered; the login link forge dash prints signs the browser in and lands on that project's Pipeline. |
dashboard.port |
| login link | The URL forge dash prints (and in a terminal opens) and forge dash url reprints, http://127.0.0.1:<port>/?project=<name>#k=<key>: the key rides only in the fragment, and the page trades it once for an HttpOnly, SameSite=Strict forge-<port> cookie and clears it from the address bar. Every /api route needs that cookie (or the CLI's token header); a browser without it shows the signed-out banner. The key is in <FORGE_HOME>/dashboard-login.json, never in the page or dashboard.json. |
- |
| login service | The per-user unit forge service install writes so the machine dashboard starts at login and comes back 30 s after a crash: a LaunchAgent on macOS, a systemd user unit on Linux. It runs forge dash --service, whose start records a restart and notifies each project with work in flight. |
- |
| sleep assertion | The one hold the machine dashboard keeps on the machine's idle sleep (caffeinate on macOS, systemd-inhibit on Linux) while any project's started pool has an active mandate or a running job at an agent stage; released when none does. |
daemon.keepAwake |
| machine cap | An opt-in bound on how many job sessions run at once across every project the machine dashboard serves, on top of each project's daemon.maxConcurrent: the machine index's settings.maxConcurrent (1–64). Unset (the default), there is none, and each project runs up to its own daemon.maxConcurrent. A shared count only: it never orders waiters across projects or stops another project's session. Inbox, office and chat sessions and gate runs never count; set or unset with forge project settings --max-concurrent <1-64|off>. |
- |
| Overview | The dashboard's cross-project page and its default route (#/overview, or the bare /), across every project: a card per registered project (active and waiting jobs, Foreman, sessions, latest activity), what waits on you first, then graphs of jobs shipped and cost per UTC day stacked by project, and the machine cap with today's and this month's spend. "Dashboard" keeps meaning the whole web app. |
- |
| project switcher | The control in the sidebar's project section that selects the project whose pages the dashboard shows (on the rail, a button that opens the palette's project <name> command); choosing one opens its same view, a missing or unavailable project can't be chosen, and Add project, ruled off below the projects, opens the Add project dialog, which registers a repo (as forge project add does) and opens its Project page. Layout, filter and window choices, session log filters and the Thread's Progress toggle are kept per project; the theme, language, sidebar and panel widths and the Rendered/Raw choices are kept for the whole browser. |
- |
| Issues | The dashboard's per-project page (#/p/<project>/issues) that lists the project tracker's items, whatever the tracker, with their triage readiness and Start for unclaimed ones; a row opens its issue panel. Old #/p/<project>/backlog, #/backlog and ?project=<name>#/backlog links land on it. |
tracker |
| issue panel | The drawer panel the Issues page opens on a row: the issue's text, comments and facts beside the job holding it, Start and its earlier jobs; it shares the job panel's shell. | tracker.github.comments |
| root repo | The repo that holds the project's .forge/, which for a project of one repo is that repo and is never listed in repos. |
repos |
| member repo | Any other repo the root repo's config lists as part of the project. | repos |
| component | A buildable unit inside a repo, of kind library, service or app. A job's components are the ones it changes: the spec's Components: header declares them, and forge verify recomputes them from the job's committed diff. |
components |
| port-bearing component | A service or app component, which holds one job port (ports in job.json, {endpoint.<component>} in commands); a library holds none. |
components, ports |
| dependency | An edge from one component to another, build when it is needed to compile or bundle and runtime when it must be running. |
planned (M004) |
| project graph | The components of all of a project's repos and the dependencies between them, drawn by the dashboard's project view. | components |
| focus | The job whose environment you are currently pointed at, set with forge focus or the dashboard, where switching focus runs the checkout steps and starts the job's stopped backing services, but starts or stops no dev server. |
- |
| checkout step | A configured action that makes a fixed path or tool follow the focused job: a link from a fixed path to the job's build, or a run of a configured command with an optional undo, undone when focus moves away. |
checkout |
| issue ref | A tracker's reference to one issue (owner/repo#12 for GitHub, a local backlog title slug, or a custom adapter's own KEY-123), kept in a job's issues list in job.json, where the first is the primary issue and one issue may sit on several jobs. |
- |
Planned in M005, except where a config key exists today.
| Term | Meaning | Config key |
|---|---|---|
| job repo | A repo the job changes, the root repo first and then each member repo a human adds with forge job repo add, so it gets its own worktree, verify evidence, branch and PR. |
- |
| repo proposal | A planner's or spec-writer's request, made with forge job repo propose, to add a member repo to its job, which parks the job until a human (or the foreman, when repo-proposal is in foreman.decides) approves or rejects it. |
foreman.decides |
| verify record | A job's verify runs, one per forge verify attempt (and per verifiers CHANGES), each bound to the commit it checked; this round's last run is the job's latest verify, and a HEAD is verified only when that run passed on it and on every member HEAD, and was not a partial pass, which verifies nothing. Only lib/engine/verify/record.ts reads it. |
- |
| partial pass | A passing forge verify --fast run: every verify group but the last passed, so the review may start (review.startAfter: fast) while a full verify runs the last group alongside it. It verifies no HEAD, so nothing publishes on one; when the full verify then fails (a late failure), the round's lens runs are cancelled and the round goes back to the builder. |
review.startAfter |
| check cache | The passes of configured commands that forge run and verify record on a clean committed tree, in .forge/runtime/checks/<job>.jsonl, keyed on the command, its arguments, command line, environment, the config and the tree; verify reuses a matching pass from the last 24 hours instead of running the command again. The gates verify adds itself, e2e and member repos never use it. |
- |
| verify-only repo | A job repo added with --verify-only, which the job checks out at its base to build and test against its changes without branching, pushing or opening a PR there. |
- |
| downstream repo | A verify-only repo Forge adds to a job because it consumes, through a declared link, a repo the job changes, so verify runs its tests against the job's changes and names it when they break. | downstream |
| checkout hook | A command run once when a job's checkout of a repo is created (today's single-repo form; per-repo hooks are planned). | worktrees.setup |
| local link | Wiring one job repo to build against a sibling job repo's checkout instead of a published version, declared as link on a components[].dependsOn[] edge and applied by forge run and forge verify. |
components |
| interim reference | What a consumer job repo points at for a dependency changed in the same job until that dependency is released: a git-ref pin, a canary version, or nothing (local, sequential); see CONFIG.md "Interim strategies". |
- |
| interim strategy | How an interim reference is made, one of canary (a published pre-release), git-ref (a pinned commit), local (local links, with the consumer PR held as a draft) or sequential (merge the dependency first), per dependency and overridable per job with forge job repo interim. |
release.interim |
The release strategy keys are in config (see CONFIG.md "Release strategy"), and forge release plan|run|status acts on them (see RELEASES.md "Releasing a project").
| Term | Meaning | Config key |
|---|---|---|
| release | Publishing new versions of one or more components, the one word for single-repo and multi-repo releases alike. | - |
| release strategy | How one repo releases, declared per repo: its versioning (semver or calver), release mechanism, registry (crates.io, npm or none), release cadence and interim strategy. |
release |
| release mechanism | The tool that cuts a repo's release, one of release-please, cargo-release, changesets, tag (a git tag made by the repo's own release.command) or script (a release script at release.script that `forge release plan |
rundrive through the script protocol, as Forge's ownscripts/release.tsdoes), whichforge doctor` checks is installed. |
| version bump | How far a script release moves the version: patch, minor or major. forge release plan infers patch or minor from the commits since the last tag and shows why; --bump overrides it. Not the release bump, which moves a consumer to a released dependency. |
- |
| release cadence | When a repo releases, one of on-merge (every merge to the default branch), scheduled (on a timer, usually in CI) or manual (when a human decides). |
release.cadence |
| release plan | The ordered repos, steps, checks and rollback for one release that forge release plan writes and a human runs with forge release run, without the Foreman. |
- |
| release gate | What keeps a consumer PR from merging while it still uses an interim reference: the seeded release gate CI check for git-ref and canary, and Forge's own gate per edge (held, bump-due, released; forge job interim <id>), which forge pr ready and forge pr merge enforce; see CONFIG.md "Interim strategies". |
- |
| release PR | Forge's own repo only: the PR from release/v<version> into develop that npm run release opens to release a version. It carries only the release commit (Release <version>: the version bump and the CHANGELOG section); a human merges it with any merge method once its CI passes, and that push to develop is what release.yml publishes. See RELEASES.md "Releasing". |
- |
| stable branch | Forge's own repo only: stable, the branch plugin installs follow. Each commit on it is one release's stable tree (the released develop commit's tree without .github/workflows/, plus the CI-built dashboard/dist/) with parents [previous stable tip, released develop commit], tagged v<version>. release.yml moves it, forward only (a ruleset keeps people off it, with GitHub Actions on its bypass list), and nothing merges it into develop. See RELEASES.md "Releasing". |
- |
| release bump | What forge verify commits once a dependency's release is recorded: the consumer's manifests, and a tracked lockfile, moved from the interim reference to the released version (forge: release bump for job <id>). |
- |
Planned in M007; a row with a config key is implemented.
| Term | Meaning | Config key |
|---|---|---|
| environment | The running components and backing services one job uses, each at its own endpoints: its per-job containers and volumes, its job databases and its background processes, beside its worktree and ports, shown for one job in its panel's Environment card and for every running one in the dashboard's Running environments section, and which Forge starts on demand, stops while the job is parked and tears down when the job finishes (forge environment). |
backing, environments.maxRunning |
| endpoint | An address (URL or host and port) where an environment serves one component or backing service: {endpoint.<component>} and {backing.<name>.port} in commands, the Endpoints: brief line and the Environment card. |
components, backing |
| backing service | Infrastructure a component needs while it runs, such as a database, cache or queue. | backing |
| isolation | How a backing service is provided to jobs: per-job (its own container per job), shared (one instance every job uses) or external (run outside Forge, which only points at it). |
backing |
| job database | One job's own database and login role on a shared Postgres backing service, cloned from a template database and dropped when the job's worktree is removed. | backing[].database |
| template database | The database a shared Postgres backing service's migrate and seed commands build once per template hash, which every job database is cloned from. | backing[].database |
| config sink | Where Forge writes a component's configuration for an environment (environment variables, a .env file, a JSON, YAML or TOML file, or a project script), chosen per component and never assumed. |
components[].config |
| secret reference | A named pointer to a secret held elsewhere (an environment variable, a keychain entry, a 1Password item, a git-ignored file) that a config sink names as {secret.NAME} and Forge resolves only when the sink renders, never writing it into job files, briefs or logs. |
secrets |
| known value | A secret value a job's sinks have resolved, or one of its job database passwords: Forge replaces it with [redacted] wherever it writes or serves text, and the secret scanner refuses to publish it. |
secrets |
| command environment | What every configured command inherits from Forge's own environment, the same in and out of the daemon: an allowlist (fixed names, a few families that never pass a credential-like name) plus the names a repo opts in, never a declared secret's source or Forge's internal variables, under /bin/sh -c with a sanitised PATH. |
commandEnv |
Planned in M008.
| Term | Meaning | Config key |
|---|---|---|
| profile | A named subset of a project's components and backing services, so a job runs only what it needs. | planned (M008) |
Words for Forge's own code, decided in #303 (design/lib-layout.md).
| Term | Meaning | Config key |
|---|---|---|
| lib layer | One of the seven top-level folders of lib/ (api, core, integrations, engine, office, server, cli), lowest first; a layer imports only layers below it (design/lib-layout.md). |
- |
| office | Forge's long-running runtime, which forge dash keeps up for each registered project: the session pool (the intake runner that answers the inbox's requests, the inbox session, per-job sessions, the office runner that runs draft and direct requests and the gate runner that decides gates), the reconciler and notifications; its code lives in lib/office/. |
- |
| integrations | The code that knows an outside system's API, CLI or file format (git, GitHub, Claude Code, Docker, webhooks, and the built-in backlog that implements the same contract), one folder per system in lib/integrations/; it holds mechanism, never pipeline policy. |
- |
| lib module | A folder inside a lib layer (lib/<layer>/<module>/) that holds one concept's files, such as lib/core/job/ or lib/engine/pipeline/. |
- |
| layer alias | A package.json subpath import (#api/, #core/, #integrations/, #engine/, #office/) that names a lib layer; imports across layers use one, imports inside a layer stay relative. |
- |
| touchpoint rule | A row of the rule table in scripts/check-touchpoints.ts: a change a diff can recognise and the companion change it needs, which npm run check:touchpoints reports as missing with the fix; companions only a person can judge stay in docs/DEVELOPING.md › Where a change goes. |
- |
| folder map | A folder's AGENTS.md: a few hand-written lines, then the table that npm run docs:map generates from each file's header comment. |
- |
| GitHub adapter | The one interface (GitHub, in lib/integrations/github/types.ts) that lib/engine/pr/ takes as a parameter for every pull request read and edit: the gh adapter (ghGitHub) in production, which lib/cli/ passes, and memoryGitHub in tests, so PR policy code never runs gh itself. |
- |
| PR snapshot | What the GitHub adapter returns for a pull request (PrSnapshot): each field of gh's JSON checked once, so an unsafe ref or a malformed head arrives as null and a PR not known to be same-repo reads as cross-repository (a fork PR is never adopted), and policy code never reads raw gh output. |
- |
Words for how the dashboard shows activity, used in the README, Settings and dashboard/AGENTS.md. The design language behind them ("station", "bezel", "pilot lamp") belongs in code, comments and design notes, never in dashboard copy.
| Term | Meaning | Config key |
|---|---|---|
| heat | The dashboard's picture of activity: a session log's frame warms while output streams and cools slowly after, and a board card's edge cools once after its job changes stage. It shows only what arrives while the dashboard is connected, never a page load or a reconnect, and reduced motion leaves each at its end state. | - |
| lamp | A small light that shows state at a glance, on a session log's nameplate (working, waiting, you, done, idle or fault) and on the status bar's indicators. It is decorative: the pill or text beside it carries the meaning. | - |
| Screen effect | The browser preference in Settings › General for the scanlines and soft glow on session logs, on by default and kept per browser like Grain; off leaves the rest of each log's frame as it is. | - |
Words for the Office (#281, M009): the Foreman directing work through mandates. Terms marked planned arrive in the named issue.
| Term | Meaning | Config key |
|---|---|---|
| Office | The user-facing name for the Foreman and everything working for it in one project: its office runs (_office), its gate runs (_gates), the owner's chats with it (_chat-<id>), its surveyors, the Office pass and the mandates they work under. Lowercase office in Code layout is the lib layer. |
foreman |
| mandate | The owner's standing instruction to the Office. It is a file in .forge/runtime/mandates/ written by the owner through forge mandate new|edit|pause|resume|close|cancel|delete or the dashboard's Office page or Pipeline, which write through the same checks: a mandate contract in its frontmatter, and the owner's guidance as free text, which briefs fence as data. A job joins one with forge job new --mandate and keeps it, and a split child keeps its parent's. |
foreman.mandate |
| mandate contract | Scope, until, maxJobs, order, decides (only narrows foreman.decides), budget, stall, onUnfinishable, scoring (all, the default, sample or off: whether its merged jobs get a score run), quality (its quality floor) and after. forge mandate show prints it as written and as it applies after foreman.decides, foreman.reserved and foreman.ship. |
foreman.mandate |
| quality floor | A mandate's quality term, {pauseBelow, minScored}: once at least minScored of its merged jobs are scored, and the running median of those scores is below pauseBelow, the Office pass pauses it (reason quality: …, notify reason mandate-quality). The running median leaves out scores still queued, held or failed, so unlike the report card's median it never reads pending. pauseBelow: null, the default, is no floor. |
- |
| mandate chain | Mandates linked by after:, each starting only once the one before has closed. forge mandate list shows each chain and its active link. |
- |
| intake | The Office turning an owner's goal into planned work: a goal mandate's drafting runs, its milestone approval, and filing the approved draft to the tracker (#434). forge mandate list marks a goal mandate intake: true. |
- |
| goal mandate | A mandate created with forge mandate new --goal: the owner states what to achieve, and its scope stays empty until its milestone draft is filed, when it becomes an ordinary scoped mandate over the filed milestone (filedAt). The goal is owner text, fenced as data wherever it is shown. |
foreman.mandate |
| milestone draft | The plan a drafting run writes for a goal mandate: one milestone with exit criteria, and up to 30 issues in waves, each naming the stat it should move. It is draft.json in the mandate's runtime dir, read with forge mandate draft show, and reaches the tracker only through milestone approval and filing. |
- |
| mandate plan | A mandate's scope issues and their dependencies, before any job exists: each issue with its wave, its job and its state (merged, running, waiting, ready or planned), the edges from each issue body's Depends on: line and each job's dependsOn, and the problems found (forge mandate plan, GET /api/mandates/:id/plan). It reads the Office pass's stored scope read and makes no tracker call. |
- |
| pipeline graph | The Pipeline's default layout: a plate per open mandate drawing its mandate plan by dependency depth, each issue a node with its job's mark, state line and stage track, and edges that turn from dashed to solid when the upstream issue merges; then the jobs in no mandate, as dependsOn chains and single nodes. The filters dim nodes and never move them. |
- |
| milestone approval | The milestone-approval gate over a goal mandate's ready milestone draft: approve files it, revise sends it back to the drafter with a note, reject closes the mandate. The owner decides, in their terminal or the dashboard's Needs you card, or a gate run when foreman.decides and the mandate's decides both list the class (never reject). |
foreman.decides |
| draft digest | The SHA-256 of a milestone draft's exact draft.json bytes: draft show, the dashboard and the gate request carry it, and a decision is pinned to it, so only the bytes someone saw are filed. |
- |
| filing | What approving a milestone draft does: the CLI creates the milestone, then each issue in wave order (wave-<n> labels), recording each in filing.json so a stopped filing resumes without filing twice, and then scopes the mandate to the milestone. |
tracker |
| drafting run | One turn of intake, run as a draft office run: the office runner claims a draft request, forge mandate draft prepare writes the survey, one forge:drafter child writes the draft, and forge mandate draft record checks and stores it with its spend. |
daemon.dailyUsd.office |
| office run | One draft or direct request run in code by forge dash's office runner, one at a time: claim (session office-run:<uuid>), the CLI steps as children (forge mandate draft prepare|record, forge office survey|board|start|resume|note) and one-shot model children (the drafter, the surveyors, at most one director call), then the ack. It never leaves a request claimed: a failure requeues it once (counted), then rejects it. It replaces the retired office session. |
daemon.dailyUsd.office |
| office runner | The part of forge dash's pool (lib/office/foreman/runs/runner.ts) that takes the _office request group while foreman.enabled holds and starts one office run at a time, under the office's daily cap shared with the gate runs. |
foreman.enabled |
| director call | The one forge:director model child a direct office run starts when a mandate has a real choice (candidates beyond its free slots, guidance or SURVEY: lines): on foreman.model and foreman.effort, with Read only, it answers one strict DIRECT: line naming which candidates start, in what order, and which it holds. A mandate under order: listed, or with no more candidates than free slots and nothing to weigh, is decided in code with no call. |
foreman.model |
| gate run | One decision of the Foreman's gate request (a job's park, or a goal mandate's milestone draft, whose gate request has no job), made in code by forge dash's gate runner, at most foreman.assistants.parallel at once: claim, the reserved check, assist, one headless forge:assistant process (its only model call), a strict ASSIST: verdict line, the gate table's decision through the policy checks, then the job's resume and the ack. Under foreman.escalations: foreman, a job's gate run that escalated or was refused adds a senior pass. No session serves gate requests (their group is _gates), and only the gate runner records a foreman decision or a Foreman hand-off, or shelves a job as the Foreman. |
foreman.assistants |
| senior pass | Under foreman.escalations: foreman, the one extra forge:assistant a gate run starts, on foreman.senior.model and foreman.senior.effort, when its first assistant escalated at a job's gate or the CLI refused its decision. It decides the gate through the same policy checks or the Foreman shelves the job for a person; reserved topics still go to a Foreman hand-off, a security review that isn't PASS is shelved without one, and it runs at most once per park (a senior-pass event). |
foreman.escalations |
| chat | The owner's conversation with the Foreman in the dashboard. Each chat is its own pool session (scope _chat-<id>), started by the owner's message and never routed a request, with chat.json and log.jsonl in .forge/runtime/chats/<id>/, written only by the dashboard server and read with forge chat. A chat acts only through the CLI, which records its actions as source chat and refuses it the reserved gates. Every chat of a project shares one daily cap. |
daemon.dailyUsd.chat |
| surveyor | A forge:surveyor model child of a direct office run that summarises one mandate's board (forge office board) in at most five SURVEY: lines, which reach the director call as fenced data. |
foreman.surveyors |
| Office pass | forge office pass: code with no model that forge dash runs every foreman.cadence minutes and on mandate changes. It enforces each mandate's contract (budget pauses, quality pauses, stalls, onUnfinishable, the self-close with its closing summary, the next link of a chain) and queues a direct request, which becomes an office run, when there is work to start. |
foreman.cadence |
| report card | A mandate's one fixed-shape quality record: what merged, how it scored, how much review and human help it took, what it cost against its budget, and the outcomes after its merges. A figure still waiting on a score run or an outcome window reads pending, never 0. forge stats --mandate <id> prints it live, GET /api/mandates and GET /api/mandates/:id serve it on every readable mandate row, and the closing summary records it at the close, then once more when none of its outcomes is open (outcomesFinalAt). The Office page shows it on each mandate: the live card on an open one, the closing summary's card on a closed one when it has a usable one. |
outcomes.windowDays |
| Office page | The dashboard's project page for the Office (#/p/<project>/office), listed in the sidebar's General section after the Overview. It lists and edits the mandates (through the same checks as forge mandate), the assistant foremen with their current gates and the latest directives in one column, beside the office runs in the other. A job in a mandate carries its id as a chip on its board card and table row. |
foreman |
| Foreman page | The dashboard's project page for the owner's chats with the Foreman (#/p/<project>/foreman), listed in the sidebar's General section after the Office page. |
foreman |
| directive | One record of the director loop in the repo audit log (and on the job it names): a choice a direct office run made as the Foreman (start, resume, note, skip) or an enforcement of the Office pass (pause, close, stall, park, cancel, and release when it plans a mandate's release), with its mandate, issue, job and one-line reason. |
- |
| merge-ready | A mandate's default until: a job at stage pr waiting on pr-review or overlap (the merge queue's hold) with an open PR (or done) has reached it. |
foreman.mandate.until |
| released | A mandate's until under foreman.ship: release: its jobs reach it when they merge, then the Office pass plans the mandate's release since the root repo's latest tag, the mandate waits for release approval, and it closes once forge release run finished that plan. |
foreman.mandate.until |
Words for automations (planned, M011; #508, #509, #510): deterministic work that fires on a trigger. Terms marked planned arrive in the named issue.
| Term | Meaning | Config key |
|---|---|---|
| automation | One file under .forge/automations/ that fires its actions when its trigger is due and its conditions hold. It is deterministic: the same inputs fire the same actions. |
- |
| trigger | What makes an automation due: schedule, manual or threshold; later tracker, job, repo and pr. |
- |
| condition | What must also hold when an automation is due: a filter, or a shell command's exit code. Never called a rule. | - |
| action | What a firing does: enqueue a request, create a job from a recipe, run a shell command, notify, assess an outside PR or shepherd one. |
- |
| firing | One evaluation that ran actions, recorded with its dedupe key, its result, and the requests and jobs it produced. | - |
| recipe | A job prompt template with variables, which an action turns into a job. | - |
| outside PR | A pull request Forge didn't open: a bot's (dependabot, renovate), a teammate's or a contributor's, same-repo or fork (planned, #509). | - |
| assessment | A read-only agent's summary, risk, timing and recommendation for an outside PR. Assessing never adopts (planned, #509). | - |
| shepherd | To adopt a granted author's same-repo outside PR as a job that keeps it mergeable and green. Never a fork PR (planned, #510). | - |
| overlap | Where two pieces of work (jobs, PRs, human pushes) change the same files or hunks; forge overlap checks one job or PR against the rest. |
- |
| overlap group | Open PRs of one mandate linked by a shared file or hunk (their overlap reports) or a dependency, transitively. A PR in no group overlaps nothing in its mandate. | - |
| merge queue | A mandate's ranked order for landing the PRs of each overlap group: dependencies first, then the ready ones, then the most input + output tokens spent. Advisory when a person merges; when Forge merges, a PR waits (overlap) while a ready PR ranked ahead of it lands. |
- |
| timing | The overlap check's fixed-rule answer for one job or PR: merge-now, wait-for, merge-first or needs-human. Not a verdict. |
- |
| tick | One pass that fires every due automation (forge automation tick, or forge dash's poll; both planned). |
- |
Some of these words already mean something in Forge. They keep those meanings:
resourcesstays the reference links agents should know about, andinfra.modestays the policy for cloud and infrastructure commands. That is why runtime infrastructure is a "backing service", never a "resource" or "infra".- "GitHub Project" always carries the prefix (
tracker.github.project,statusSync: project). Bare "project" means the glossary's project. - The top-level
project:block (name, instructions) today describes the root repo of a one-repo project. - A job's components were once its
services(the job field and the spec'sServices:header), which still read as deprecated aliases. A component of kindserviceis not a backing service. - "Model profiles" in CONFIG.md are
runtime.modelspresets from/forge init. "Profile" alone means the glossary's profile. - A job's
dependsOnis a job dependency. "Dependency" alone means a component edge. - "Environment" alone never means environment variables (say "environment variables"), and "focus" never means a test's focus marker or keyboard focus.
- "Hand-off" alone means a session handing a job to another with
forge requests add resume; the Foreman's always carries the name ("Foreman hand-off"). - "File map" is a spec's
Files:table; a folder'sAGENTS.mdis its "folder map". - "Integrations" never means the integrate stage or the integrator (bringing a branch up to date with its base), nor integration tests (
test/integration/). - "Office", capitalised, is the Office (the Foreman, its gate runs and its mandates); lowercase "office" is the lib layer and runtime in
lib/office/. The Foreman's work on draft and direct requests is "office runs"; the "office session" is retired and names only that former long-lived session. - The Office's "intake" (a goal mandate's drafting runs) differs from a job's intake,
forge requests add resume --intake run|next|new, which says how a job starts. The intake runner does a job's intake: it is no part of the Office. - "Milestone" means a tracker milestone (a group of planned work). The Thread's one-line rows for a job's events are "progress lines".
- "Chat" is always the owner's conversation with the Foreman; it never means the job panel's Thread, whose messages are a job's agents and decisions.
- "Layer" alone keeps its meaning in the architecture docs (engine, roster, repo layer, runtime state). The folders of
lib/are "lib layers". - An "agent run" is one run of a role's agent (
runHistoryon its agent record); a job'sruns[]are orchestrator sessions' stints on the job, and a "verify run" is oneforge verifyattempt. - "Merge queue" is a mandate's ranked order for its overlapping PRs; GitHub's own merge queue, and a merge queued with
gh pr merge --auto, always carry their names. - "backlog" means the local tracker (
tracker.kind: local,.forge/backlog.mdand its title-slug refs) and the pipeline's first stage (backlog); the dashboard page that lists any tracker's items is "Issues", and its data routeGET /api/backlogkeeps its name. - "Workers" is the status bar's pool of job sessions; "agent" stays a pipeline role's subagent (agent stages, the Agents view and tab), never a pool session.
- "Rule" stays the step decider's pipeline rules (
RULESinlib/engine/pipeline/step/rules.ts); automations have conditions, never rules. - "Verdict" stays a reviewer's; the overlap check gives a timing.
- "Adopt" stays the PR-adoption step (
forge pr find); shepherding adopts, assessing never does. - A mandate is goal-directed and judged, while an automation is deterministic, so the two words are not interchangeable.
The new words build on these, which exist today.
| Term | Meaning | Config key |
|---|---|---|
| job | One unit of work that Forge takes from request to PR, in its own worktree. | - |
| title schema | The rule PR titles and job names follow: conventional commit subjects by default, plain, or the repo's own pattern. The approver writes the PR title on pr.md's Title: line, Forge checks it before the PR opens, and a job is renamed to it (or to its spec's heading) as titles.job says; its id and branch never change (docs/CONFIG.md "Titles"). |
titles |
| move | A change to a job's stage, state or waitingOn made through lib/engine/pipeline/moves/apply.ts, which then stops or tears down its environment, queues the Foreman's gate request and mirrors it to its tracker; notifications follow every transition. |
- |
| shelve | A person setting a job aside with forge job shelve, or the Foreman doing so when a senior pass can't settle a gate: it waits on shelved, spends nothing, keeps its PR, isn't counted as waiting on you, and only a person takes it off the shelf (forge job unshelve, or the dashboard's Shelved list in Needs you). Unlike a park, nothing resumes it on its own. |
- |
| output mode | How a forge call prints: human (rendered text for a person at a terminal) or agent (compact JSON, the CLI's contract), chosen by --json, --mode, FORGE_MODE, then whether stdout is a terminal (docs/CLI.md "Output mode"). |
- |
| activity log | The timestamped lines a foreground forge dash prints after its banner in human mode, of three kinds: session (session transitions), http (requests worth noting) and job (newly appended job events); --quiet and agent mode leave only the banner (docs/CLI.md "Output mode"). |
- |
| Foreman | The Office's director, which directs the work of active mandates (which in-scope issues start next) through office runs and their director calls; its gate decisions are made by gate runs, for jobs under foreman.decides, narrowed for a job in a mandate by that mandate's decides. |
foreman.decides |
| Foreman hand-off | The Foreman leaving a gate it was asked to decide for a person (a reserved topic or class, the assistant escalating, or the CLI refusing its decision; under foreman.escalations: foreman the last two get a senior pass, which shelves instead of handing off), recorded by the gate run (a foreman-handoff event) and shown as left for a human (foremanHandoff) until a decision answers that park or the job parks again. |
foreman.reserved |
| Workers | The status bar's indicator and popover for the daemon pool's job sessions, one per running job up to the cap (its live/cap count): Start/Stop, the default permission mode for job sessions and a row per job session. The inbox session has its own Inbox indicator. | daemon.maxConcurrent |
| launch mode | The permission mode forge dash --permission-mode gives every job and inbox session of that run, in every project, that has no choice of its own; held in memory until that forge dash stops; shown in the banner, the Workers popover and forge daemon status; audited as daemon-mode, source launch. |
- |
| session rotation | A job session retiring its conversation once a turn's context (its last main-loop API call's input, cache-read and cache-creation tokens) passes the threshold: it stops resuming, stops at the next safe boundary (idle, nothing in flight, not kept by its job's agents), and its next spawn starts a new conversation; logged as rotated, then stop with reason rotate. The inbox session starts a new conversation at every spawn instead. Not log rotation (retention.logMaxBytes). |
daemon.freshAfterTokens |
| prompt history | The record of the permission prompts pool sessions were answered on, with no input field (.forge/runtime/permission-prompts.jsonl: scope, tool, suggested rules, decision, reason; a rule can carry part of the command, minus known secrets), from which forge daemon prompts suggests daemon.allowedTools rules a person may add by hand. |
daemon.allowedTools |
| metered spend | What the supervisor measured a daemon session spend, from claude's own per-turn cost report, kept in .forge/runtime/meter/; budgets enforce it. In the spend ledger, a job's part beyond its covered agent ends is role job-session. |
daemon.dailyUsd |
| session usage | A daemon session's own token usage per turn, from the result line's usage: main-loop calls only, never its subagents'. By lane job (a session-usage job event), inbox and office (.forge/runtime/session-usage/); forge stats reports it as cost.orchestrator and the spend ledger as role orchestrator. Budgets never read it. |
- |
| lease | A job's one claim on who drives it (lease in job.json: driver, epoch, since, renewedAt, expiresAt): taken by forge job claim, renewed only by the driver's own activity, expired by the supervisor when the driver's session exits, and live until expiresAt passes; nobody else may claim a live lease without --force. |
- |
| epoch | The lease's counter, one higher at every change of driver and never lower; a driver passes the epoch its claim returned as --epoch, and a write with an older one is refused (stale_epoch), so a session that was taken over can't write after it. |
- |
| code driver | A job scope's driver under daemon.driver: code: forge dash's loop that claims under its stable id, applies the turn's requests with forge job apply, runs forge job advance and one role run per spawn as child processes, and hands only a procedure (RC1's recall eval) to a session. See Daemon runtime › Code driver. |
daemon.driver |
| role run | One pipeline role run as its own headless claude -p --agent forge:<role> child in the job's worktree by forge job agent run, rather than as a subagent of the job's session: Forge records its start, attach and end itself, takes its usage from the child's own result line, and denies every permission prompt unattended, or relays them to the dashboard under the code driver. Its run log and cost sidecar live in .forge/runtime/agents/<id>/. See Daemon runtime › Role runs. |
daemon.command, daemon.allowedTools |
| context session | A headless child that reads a round's shared inputs (spec.md, design.md, build.md, the verify and verifiers reports, scope.md and the round's diff) once and replies READY, so each review lens and rework build of that round forks it (--resume <id> --fork-session; a rework build or re-run lens that resumes its role's last session does not fork, see rework resume) and starts with those inputs already in context, served from the prompt cache. There is one per round, agent, model, effort and trusted prefix; a fork never names another agent. forge job agent run starts or forks it, records it in job.contexts and its usage under role context, and runs the role cold, with a reason, when it can't. See Daemon runtime › Role runs. |
- |
| rework resume | A rework round's builder or re-run lens continuing its role's last role run (claude --resume <session>) instead of starting fresh or forking the round's context session, so it keeps what it already read. Step decides it per role and records it on agent-start as resume, or as resumeSkipped with why not: off, last run failed, no session, model changed, spec changed, no transcript, context unknown or context over ceiling (over 120000 tokens). The brief is the same either way. See Daemon runtime › Resume. |
pipeline.resumeRework |
| trusted prefix | The one file a role run gets as --append-system-prompt-file: the main checkout's copies of the role's instruction files, the learnings and the role's notes, and nothing an agent wrote. Named by its content under .forge/runtime/prompt-prefix/, so every lens, round and job with the same files shares it and the prompt cache serves it; a refused source runs the role without one. See Untrusted input. |
project.instructions |
| reconciler | The pass (lib/office/reconcile.ts) that finds running jobs nothing drives (no request routed to them, no busy session, no live lease) and resumes each once, then parks it on escalation if it made no progress since, and closes resume requests a session already acted on or no job can act on; forge dash runs it every 30 s and forge sync runs it when no dash does (it replaces what was called a stranded job). |
daemon.turnTimeoutMinutes |
| intake runner | The part of forge dash's pool (lib/office/inbox/) that answers the inbox's requests (sync, next, run, retro, eval-run) in code instead of an inbox session: one at a time, it claims each under the inbox's intake session id, runs fixed forge commands as CLI children in the _inbox scope, hands each new job off with a resume, and acks with a one-line result; a next first runs readiness triage as one headless forge:triage child. Only a request type it doesn't handle reaches the inbox session. |
daemon.enabled |
| split check | Under pipeline.plan: auto, the spec-writer deciding one job or a split before any planner runs, on a request over the planner threshold (600 characters, or 3 list or heading lines) with a split mode other than never; its brief says Split check: yes · split mode <ask|auto>. One job: a full spec with Split: no. A split: a short spec.md with Split: yes and a ## Why, and the job goes to the planner (rule SP8). |
pipeline.plan |
| clean pass | A job in decide whose outcome is already known: every lens of its panel passed, the gate check since the review found no escalation reason, and no protected path, runbook, unproven acceptance criterion, instruction change, recall eval or wait stands in the way, with auto-merge off. With the key on, Forge records its own APPROVE (forge job decision --clean, rule DC13) and renders decision.md and pr.md instead of running the approver. |
approver.skipWhenClean |
| rework panel | The lenses that re-run on a rework round under review.onRework: narrow (the always and alwaysOnRework lenses, security by default, those whose last verdict asked for changes or that have none, and those whose paths the fix touched), while every other lens on the job's panel keeps its last pass. |
review.onRework |
| outcome | What happened to a merged job inside its window after the merge (reverted, follow-up bug issues, churn), open until the window closes and final after, measured by forge sync and stored as outcome in job.json. |
outcomes.windowDays |
| autonomy rate | The share of merged jobs with a final outcome that shipped with no person's rework, revision, decision, PR feedback or edit, and were neither reverted nor followed by a bug; the strict autonomy rate also counts a person's approval at a gate config requires (spec, split, repos, release, issue link, infra, protected paths, or an escalation park that lists only protected paths and a runbook). | - |
| score | A sampled merged job's, or a merged job of a mandate that scores all, post-merge quality score from the judge, 0-5, against the spec's acceptance criteria and the merged diff; queued by forge sync, recorded by forge job score record and stored as score in job.json (held when a budget stopped it, failed without a valid score.md). |
scoring.sample, scoring.model |
| score coverage | How many merged jobs were sampled for a score, and how many of those were scored, held, failed or are still queued (scoreCoverage in forge stats). |
scoring.sample |
| churn | Later non-Forge commits on the base branch, inside a job's outcome window, that touch a file the job's merge changed; a soft signal reported beside the autonomy rate, never counted against it. | outcomes.windowDays |
| total-round ceiling | The most build rounds a job runs, whoever opened them (the builder, a person, the Foreman, or a CI rework), before each further round needs a person's rework, twice maxRounds by default; past it step parks the job on rounds-exhausted (rule B7) and the Foreman is refused there. |
pipeline.maxTotalRounds |
| CI rework cap | The most CI reworks in a row, with no person's action between, that forge sync starts on a PR whose checks fail; the next red head waits on pr-review for a person, with a reason naming the failing checks. |
pr.maxCiReworks |
| CI re-run | forge sync's one re-run of a PR head's failed GitHub Actions checks after the Foreman's CI rework of that head ended with no new commit; if they fail again, or can't be re-run, the job waits on pr-review for a person with a CI re-run: reason and no gate. It never counts toward the CI rework cap. A person's re-run (forge pr rerun, the dashboard's Re-run failed checks) logs the same ci-rerun event with their actor, so sync counts it as that head's re-run and never re-runs the head itself. |
- |
| merge gate | A park after the PR opened that holds the merge until a person decides on the open PR: the one escalation park (PR15), whose reason lists the approver's escalation and every open gate reason (escalation: <rules>), or a missing recall eval. forge pr gate says why on the PR, a bullet per reason, and labels it; one person's approve at the escalation park clears every rule it lists. |
pr.needsHumanLabel |
| gate reason | A mechanical reason a job needs a person before merge, which forge job gate computes from job facts once per review and logs as a gate event: protected-paths, lens-escalate, runbook, acs, version or dependencies, each with a CLI-composed detail. The approver reads them as facts, the escalation park lists them, and a gated decision never auto-merges. protected-paths, lens-escalate and runbook are human-only: the Foreman never clears them. |
- |
| held push | A push forge pr open won't make until a person approves it, because pushing is itself the risk: a CI config change, a security review that isn't PASS, or secrets the scan only reported. Nothing leaves the machine meanwhile (push_held). |
- |
| escalate floor | The paths no unattended merge lands, whatever policy.protectedPaths says: anything under .forge/ (in any case), Claude Code's own control files (.claude/, CLAUDE.md, AGENTS.md, .mcp.json), the instruction files project.instructions names, and test, build or CI config; forge pr merge without --now refuses a PR that touches one (reason: floor), so only a person merges it (docs/CONFIG.md "Merge"). |
merge.auto |
| required check | A check a PR's merge needs, bound to its source: a name from merge.requiredChecks (any check run, or one from a named app or workflow file, or a commit status from a named login), else from the base branch's protection; forge pr merge without --now waits while one has not reported from its source and refuses one that fails, is SKIPPED or NEUTRAL, or reports from more than one source (docs/CONFIG.md "Merge"). |
merge.requiredChecks |
| human-only operation | A CLI operation only a person may run: forge pr merge --now, forge job budget --set or --ack, and forge budget ack. It takes its go-ahead from a channel a session's children can't reach, never from the absence of FORGE_DAEMON: a person at a terminal who types the job id (or period) back (all three), or a person using the dashboard's Merge now (pr merge --now), its Approve & continue on the budget gate (job budget) or its Acknowledge in Needs you (budget ack). An agent, a script or a configured command is refused with code human_only (docs/architecture/daemon-security/human-only-operations.md has the channels per operation). |
- |
| unattended job budget | The spend limits a job in a daemon-enabled repo gets for each of tokens, usd and minutes that neither config nor the job's own budget sets. |
daemon.jobBudget |
release gate class |
The Foreman's approval of one job's release plan (forge release plan --job) or of an until: released mandate's release plan, which stands in for forge release run's publish prompt without a terminal, for that exact plan only, which stays a human's unless a project adds release to foreman.decides and removes gate:release from foreman.reserved (not the release gate, the CI check on interim references). |
foreman.reserved |
| prompt cohort | The jobs whose last start of one role ran on the same prompt hash (promptHash on agent-start), grouped by forge stats --by prompt so a prompt change can be compared with the prompts before it. |
- |
| settled experiment | An experiment ledger entry whose status forge experiment evaluate wrote (kept, reverted or inconclusive, with its n, method and interval); it is history, and the notes check refuses any change to it. |
improve.experiments |
| progress line | A one-line row the job panel's Thread shows between the messages for a job event a person follows: a new stage, a parked gate, an agent's closing reply, a round's checks or reviews, the decision, the PR, merge conflicts or a note. It never counts as unread. | - |
| scenario | A named dashboard state, one JSON file in test/fixtures/scenarios/, that npm run scenario, npm run dev -- --scenario and the render check seed into a scratch repo through the CLI alone, with the texts each view must show (docs/TESTING.md "Dashboard scenarios and the render check"). |
- |
| render check | npm run test:render: every view of every scenario, and the job and issue panels, loaded in headless Chrome against a dashboard build, failing on a console or page error, a 5xx or missing text; CI's render job runs it, outside the verify list. |
- |
| version step | One named entry ({ id, up }, or { id } for /api) in an append-only version list (lib/core/versions/, lib/api/versions.ts); a shape's version is its list's length plus one, so a shape change appends a step and never types a number. |
- |
| file map | The Files: table that ends a spec's Approach: one row per file the builder will touch or reuse, with its symbols, the change and the tests that cover it; forge job acs reports a spec without one as incomplete (fileMap, incomplete). |
- |
| peak context | The size of a role run's last request (input, cache read and cache write): the context it carried by its end, since context only grows within a run. forge stats gives its median, p90 and n per role as cost.byRole.<role>.peakContext. |
- |
| recall fixture | A frozen diff in the main checkout's .forge/evals/recall/<name>/, with the lenses that review it and its planted defects (none for a clean fixture), that forge eval recall grades reviewer prompts against. |
evals.recall.paths |
| worktree seed | A private, Forge-owned copy of a fresh base worktree's dependency paths and caches, which new job worktrees clone copy-on-write while their key files match, instead of running setup. | worktrees.seed |
| finding key | A review finding's lens plus the first four words of its title, lower-cased, without its location, code spans, paths, punctuation and stop words; forge retro prepare lists findings that share one in 2 or more jobs under ## Recurring findings across jobs. |
- |
| unresolved finding | A finding from a lens's earlier review that a round 2+ reviewer of the same lens raises again because the code still has it, marked (unresolved from round <n>) right after its location. |
- |
| missed earlier | The (missed earlier) marker a round 2+ reviewer puts right after the location of a new finding in code unchanged since the commit its previous review saw (Changed since:), so a count of markers in review/round-*/ tells misses from regressions. |
- |
| CLI copy | The CLI's own copy of a job's job.json and events.jsonl under .forge/runtime/job-records/<id>/, written first on every store write and read by Forge, so an edit to the job folder's files is ignored; jobs created before it have none and read their job folder. |
- |
| protected set | The main-checkout paths that decide what forge runs or what every agent reads with no review (PROTECTED in lib/core/config/trust.ts, plus the configured instruction files), which the trust digest hashes and a daemon session may not write. |
project.instructions |
| write root | A directory a daemon session may write without a prompt: the main checkout's .forge/jobs/ and every worktrees root; its file tools are scoped to them at spawn and the write guard allows nothing else. |
worktrees.root |
| confine digest | git status over the protected set, every nested CLAUDE.md and an in-checkout hooks dir, plus the content of each file it lists, taken when a human starts the pool and compared after every turn and before every spawn (the post-turn check). |
- |
| mechanical finding | A recurring finding a script could decide from the diff or the tree, for which the retro proposes a check (an invariant test, a lint rule or a verifier) instead of a learning; every other finding is a judgement finding. | - |
| agent run | One start-to-end of a role's agent on a job, recorded by forge job agent <id> end in that agent's runHistory (the newest 50) with its round, times, status, model, billing split and context composition; a role with rework has several, and the drawer's Agents tab lists them per role. |
- |
| billing split | An agent run's tokens as the API bills them: cache read, cache write, fresh input and output, plus a "not split" rest when the run reported only a total (--tokens). |
- |
| context composition | An estimate of what filled an agent run's context at its last request: the start prefix (Forge prompt and harness), earlier runs of a resumed transcript, tool results by tool (an MCP server's together), assistant output and user turns, scaled from transcript text sizes so the parts sum to that request's exact input. | - |
| start prefix | An agent run's first request's whole input (fresh, cache read and cache write): the Forge prompt (the role prompt and brief, estimated from their text) plus the harness share, Claude Code's system prompt, tools, MCP and skills, which transcripts don't show. | - |
| related tests | The test files forge run <job> <command> --changed derives from a job's changes since its base: changed test files, the tests relatedTests.map names for each changed file, or the whole command when a shared helper (relatedTests.full) changed. |
relatedTests |
| transcript stats | The counts forge retro prepare takes from each agent run's Claude Code transcript (turns, tool calls and errors, repeated failing commands, permission denials, re-read files, non-zero forge exits) into transcripts.json, per run and per role; counts, ids and short keys only, never transcript text or a path. |
- |
| deep read | One of the worst agent runs of a retro's window, ranked by turns per task, then tool errors, then rework rounds, whose condensed, fenced log a digest agent reads; at most improve.transcripts.max per retro, 3 per digest. |
improve.transcripts.max |
| digest agent | The forge:digest role: reads one digest input of up to 3 deep reads and writes friction-<n>.md, at most five friction patterns for the retro agent, with Read and Write only (not the confine digest). |
- |
| approval notes | approval-notes.md in a job's folder: the notes a person gave with approve-spec and the hints added with forge job note --for builder, rendered from the job's events (never the Foreman's), which the builder brief lists as untrusted hints. |
- |