AGENTS.md
Rama main · réplica de lectura del repositorio original.
# AGENTS.md
This file is the public source of truth for AI coding agents (Cursor, Claude
Code, GitHub Copilot, Codex, etc.) and human contributors who want to know
**what is binding** when modifying this codebase.
It is the contributor-friendly distillation of our internal SSOT policies.
The deep, regression-grade rationale lives in [`docs/internals/`](docs/internals/);
the user-facing concepts live in [`docs/concepts/`](docs/concepts/).
> **For setup instructions** see [CONTRIBUTING.md](CONTRIBUTING.md). This
> document is about *what to write* once you are set up.
---
## Quick Map
| You want to… | Read |
|---------------------------------------|-----------------------------------------------------|
| Understand the system in 5 minutes | [docs/concepts/architecture.md](docs/concepts/architecture.md) — user-facing explanations of agents, jobs, tiers live alongside it |
| Set up, build, test | [CONTRIBUTING.md](CONTRIBUTING.md) · [docs/develop.md](docs/develop.md) |
| Add a new agent / job / phase node | This file, then [docs/internals/](docs/internals/) — incident-driven rationale, enforcement greps, test names |
| Touch the universal / custom-agent runtime | [Universal Runtime](#universal-runtime--one-jobtype-file-defined-jobs), then [docs/internals/44-universal-job.md](docs/internals/44-universal-job.md) |
| Touch the pipeline scheduler (cron, chaining, approval gates) | [docs/internals/46-pipeline-scheduling.md](docs/internals/46-pipeline-scheduling.md) |
| Author or edit a prompt template | [Prompt Engineering](#prompt-engineering) |
| Touch the LangGraph state machine | [LangGraph State Management](#langgraph-state-management) |
| Make a change that crosses BE↔FE | [Cross-Package Contracts](#cross-package-contracts-antshared) |
| Touch a security boundary (paths, origins, child processes, resource budgets) | [`docs/internals/security-posture.md`](docs/internals/security-posture.md) — the seven-axis SSOT |
| Self-host, design input, custom prompts | [docs/guides/](docs/guides/) |
| Run the custom-agent + MCP example end-to-end | [examples/README.md](examples/README.md) — not product code. The one runtime reader is the builder-handoff composer, which inlines `custom-agents/ops-team` and `pipelines/weekly-ops.yaml` as a bundle's Part 3, so both images ship `examples/` beside `docs/` |
If a rule here contradicts the code, the **code is authoritative** for runtime
behaviour — please file an issue so the document gets fixed.
---
## Architecture in One Page
Ant is a **modular monolith** packaged as four independent processes
(`ant-api` 4100 / `ant-realtime` 4101 / `ant-job` / `ant-preview` 4102) that
communicate **exclusively via Redis** — Pub/Sub, Key-Value, BullMQ. There is no
direct HTTP between processes. The backend is hexagonal: `composition/` entry
points, `core/` domain logic, `agents/` LangGraph graphs, `infrastructure/` and
`periphery/` adapters.
A job flows: HTTP request → BullMQ enqueue → `JobWorker` spawns `job-runner.ts`
as a child → `orchestrator.ts` routes to a LangGraph agent graph → state
broadcasts over Pub/Sub → completion publishes to `job:status:updates`. Jobs are
interruptible and resumable; checkpoints live at
`{featurePath}/sessions/{agent}/{jobType}.json`.
Process table, entry points, and the job-type → agent → output matrix are in
[docs/develop.md](docs/develop.md); the narrative walkthrough is in
[docs/concepts/architecture.md](docs/concepts/architecture.md) and
[docs/concepts/jobs.md](docs/concepts/jobs.md). Read those before changing
topology; the rules below are what binds when you write code.
---
## Unified Distributed System Principle
**Ant is always a distributed system. There is no separate "local mode"
implementation.** Local and Cloud differ only in where the infrastructure
runs and in two narrow fork points (auth tenant resolution and Figma MCP
transport — desktop is local-only by nature). The data plane — Redis,
BullMQ, Pub/Sub, separate processes on individual ports — is identical.
### ❌ Forbidden
- `if (mode === 'local') / if (mode === 'cloud')` branches that produce
divergent business logic.
- In-memory `Map` / `Set` that mirrors Redis SSOT state (job-completion
flags, user-stopped flags, kanban snapshots) as a "fallback".
- Code paths that assume Redis or BullMQ might not exist.
- Skipping authentication based on mode.
### ✅ Correct
- A single code path that uses Redis, BullMQ, and Pub/Sub unconditionally.
- `StateStore` (Redis) is always available — never `undefined`, never behind
`if (stateStore)`.
- Tenant resolution is always enforced. Cloud mode authenticates every request
(JWT); local mode resolves the single `local:local` tenant WITHOUT an HTTP
auth gate — `ServerConfigurator.setupAuthentication` early-returns, because
local mode is a single-developer trust boundary. Never widen that fork beyond
auth-tenant resolution.
If it doesn't work without Redis, **fix it — do not add an in-memory fallback.**
---
## Node Graph Layout — Phases Are Task-Type Blind (R1)
**Phase nodes, routers, parallel orchestrators, and common tool handlers MUST
be blind to `task.type`. Task-specific logic lives only in
`tasks/{taskType}/hooks/`.**
### ❌ Forbidden
- `if (task.type === 'verification')` (or `'error'`, `'feature'`, etc.)
inside `nodes/`, `routers/`, `parallel/`, `common/tool/handlers/`.
- `{ currentTask: { type: '...' } } as any` to sneak task-type logic into
state-less contexts.
- Domain state fields (`_verificationTracker`, `_fooHistory`, etc.) on
`state.ts` — they belong in `tasks/{type}/model/Session.ts`.
- Routers mutating state — routers are pure predicates.
### ✅ Correct
- `hooksIfActive(state)?.{hook}?.(...)` at phase-node call sites (state
available).
- `hooksForTaskType(ctx.currentTaskType)?.{hook}?.(...)` at tool-handler /
orchestrator call sites (no state, just ctx).
- Each task type owns `tasks/{type}/index.ts` exporting `{ hooks: TaskHooks }`
and registers itself in `tasks/_shared/registry.ts`.
The full 8-axis layout and rules R1–R5 live in
[`docs/internals/NODE_GRAPH_LAYOUT.md`](docs/internals/NODE_GRAPH_LAYOUT.md).
---
## Three-Axis Task Modeling — type / band / priority
Task classification is split across **three orthogonal axes** observed by
different actors:
| Axis | Observer | Decides | Domain |
|-----------------|----------------|-----------------------------------------------------|----------------------------------------|
| `task.type` | LLM | "What action mode is this task in" | `feature` / `error` / `verification` / `ui` / `design-system` / `test-code` / `doc` / `setup` / `explain` |
| `task.band` | Orchestrator | Scheduling position by dependency order | feature: `'foundation'` / `'platform'` / `'integration'` / `undefined` · setup: `'root'` (project/framework/workspace-level, priority 100) / `undefined` (package setup) |
| `task.priority` | TaskQueue | Sort order in the queue | Integer — sort comparison only |
**`task.priority` may be compared only inside `TaskQueue.push()`'s sort
callback.** Phase nodes, routers, parallel scheduling, classification, and
type decisions MUST NOT compare priority semantically. The single legal
priority-to-meaning translation lives in
`decompose/responseParser.ts::deriveBandFromPriority` — a **strict reverse lookup
over the `TASK_PRIORITY` window map** in `code/state.ts`, so the band→window
forward map and the priority→band reverse lookup cannot drift. Strict means
window-exact: `setup.root` is `100..100` (the unique workspace-level setup, which
dequeues first — `101+` is band-absent package setup), feature bands are
`foundation 220..259` / `platform 260..299` / `integration 600..649`, and the
adjacent `design-system 200..219` window never derives a feature band.
Everything downstream reads `task.band` (feature / setup) or `task.type`
(everything else) — never the integer.
`band` is carried only by `FeatureTask` (`FeatureBand` = foundation / platform
/ integration) and `SetupTask` (`SetupBand` = `'root'`) via discriminated
union — `{ type: 'verification', band: 'root', ... }`, `{ type: 'feature',
band: 'root', ... }`, and `{ type: 'setup', band: 'foundation', ... }` are all
compile errors.
A `band:'root'` setup owns ONLY root-level artifacts (workspace manifest +
member glob + shared config + infra in a monorepo; the lone manifest + tooling
config in a monolith) and creates **no** member directory or name. Every other
member is created and named by its own band-absent setup — the workspace glob
discovers it. This is the structural fix for stranded "husk" package
directories (two setups naming the same boundary differently).
---
## Task Description Authorship — `BaseTask.description`
The fourth task axis is **content**: `description` is the LLM-authored
per-task scope of work — the work statement plan/execute receive, the Kanban
card body, and (when no plan is sealed) the ENTIRE execute instruction.
**Assigning the job-level user directive (`state.directive` /
`state.overrideDirective`) to `task.description` is FORBIDDEN.** The directive
reaches every prompt on its own channel (`# User Directive` / `{{directive}}`);
copying it into tasks makes every task identical, erases the decompose LLM's
per-task reasoning, and double-injects the same text under contradictory
framing. Also forbidden: a second field carrying per-task scope alongside
`description` (the historical `DesignTask.sectionScope` split), and two render
sites for the same field in one prompt.
Legal producers: the decompose/revise LLM verbatim, or a deterministic helper
that *names* the unit of work without pasting the directive
(`specDecompose.buildRevisionScope`, `prdSync` task factories). Floor:
non-empty after trim (`isTaskDescriptionAuthored` in `@ant/shared/task.ts`),
enforced at task creation — code decompose retries with framing
(`MissingTaskDescriptionViolation`), design ui/system/game-art throw into
their repair round, spec synthesizes `buildFullSpecScope()`. Never enforced in
`TaskQueue.from` (checkpoint restores must not throw).
`sectionScope` survives only as a local variable in design
`execute/intent/system.ts` (catalog-computed section assignment) — it is not a
task field.
```bash
rg -n "description:\s*(state\.)?(override)?[dD]irective\b" packages/*/src --type ts # Expected: 0
```
Regression guard: `tests/policy/task-description-authorship.test.ts`.
---
## Tier × Verification Matrix (Code Job)
The 5-tier execution model is a job-neutral SSOT in
`core/executionTier`. Code jobs follow this matrix at decompose time:
| Tier | Meaning | Writes | Tasks at decompose | Verification |
|------|----------------------|---------|--------------------|--------------|
| 0 Reflex | Read + text answer | Forbidden | 0 | N/A (direct) |
| 1 OneShot | Limited writes, no verification needed | Allowed | 0 | None (direct) |
| 2 Exploratory | Single unit of work | Allowed | Exactly 1 | Two-cycle: apply → reverify via `_shared/verify/` |
| 3 Task | Multiple units | Allowed | ≥ 2 with verification task | Verification task gates via `_shared/verify/` |
| 4 RefsGrounded| Tier 3 + refs-grounded | Allowed | ≥ 2 | Same as Tier 3 |
The verification infrastructure lives in
`tasks/_shared/verify/` as the **single SSOT**. Tier 3/4 dedicated
verification tasks and Tier 2 self-verify tasks share it via `composeBundle`.
For the full background and the runtime-escalation paths used by `batchSplit`,
see [`docs/internals/17-code-verification-task.md`](docs/internals/17-code-verification-task.md).
---
## Retry Authority — `violation.isRetryable`
**Whether a violation is retryable is decided once, at the violation's source
of truth: `violation.isRetryable: boolean`.** `checkTaskStatus` reads this
flag and routes; it never re-judges via score, retry count, or type lookup.
### ❌ Forbidden
- Scoring violations or applying retry-count penalties inside any phase node.
- "critical type" arrays that override `isRetryable: false`.
- Pre-filtering violations sent to plan ("top-N same-type slice").
- Returning a violation with `isRetryable` left `undefined` — it will be
dropped by the strict equality check.
### ✅ Correct
- Set `isRetryable: true | false` explicitly at every violation creation
site (`tasks/*/hooks/check.ts`, `nodes/checkTaskStatus/evaluate.ts`).
- `nodes/checkTaskStatus/index.ts` only does
`violations.filter(v => v.isRetryable === true)`.
- Grouping, prioritisation, and root-cause selection live in the plan
prompt, not in phase code.
---
## LangGraph State Management
### Channels must be defined
When using a state field, define it in `channels` first.
```typescript
// ❌ Wrong
(state as any).parsedUiDocs = value;
// ✅ Correct
const graph = new StateGraph<GraphState>({
channels: {
parsedUiDocs: null as any, // reducer
// ...
},
});
state.parsedUiDocs = value;
```
### Derived channels
`state.executionTier?: ExecutionTierId` is derived — decompose writes it once,
after the LLM emits `<executionTier>N</executionTier>`. Phase nodes read it only
through the `getExecutionTier(state)` facade (`executionTier.breadcrumb(...)` /
`.boundary(...)`), and must never inspect `mode` / `complexity` literals
themselves (`if (state.resolvedAction?.mode === 'explain' && …)`). Mode dispatch
lives in exactly one place: `Tier3Task`'s constructor.
---
## Canonical Tag Rendering
Every canonical `<tag>` emitted by a node — LLM-streamed or back-channel —
**must** be registered in
`packages/ant-cli/src/core/streaming/transformers/SpecialTagTransformer.ts`.
Rendering rules live there only.
### Forbidden
- Emitting a new tag without registering a transformer entry.
- Calling `formatRACForChat` / building tag-formatted text outside
`SpecialTagTransformer`.
- Adding `insideXxx` flags to `XMLStreamParser` to suppress a tag —
suppression belongs in the transformer (`{ consumed: true }`).
- Silently swallowing chat-emit failures (`try {…} catch {}` with no log).
### Correct
- New canonical tag → add `this.register({pattern, transform})` in
`SpecialTagTransformer.initializeTransformers()`. Use a `transform*` method
for formatted output or a `() => ({ consumed: true })` suppressor.
- Locale-dependent labels live in sibling SSOT modules and are imported by
the transformer — not hard-coded in node files.
The current registered inventory is documented in
[`docs/internals/36-output-tag-matrix.md`](docs/internals/36-output-tag-matrix.md).
---
## state.artifacts is RAC-bound
**`state.artifacts` is always a subset of `resolvedAction.refs ∪ context`.**
Only two functions write to the artifact pool:
1. `loadResolvedArtifacts(resolvedAction, featurePath)` — RAC-based load.
2. `appendOrUpdatePool(pool, task.files)` — design-job intra-job
self-output.
Phase nodes and resolve must never wholesale-walk `architecture/**`,
`visual/**`, or `plan/**` to populate the pool. If you need a presence flag
that pre-dates RAC (used during triage / detect), use `state.workspaceState`
— that is the SSOT for "does this directory exist on disk".
`read_file` / `list_files` enforce a RAC whitelist for **explicit** pipelines.
The policy SSOT is
`code/nodes/decompose/racGate.ts` — `computeRacScope` (returns a scope only when
`source === 'explicit'` ∧ `hasExplicitFields` ∧ `refs ∪ context` non-empty; infer
pipelines get `undefined` and may discover freely), `decideRacGate`, and
`isWithinRacWhitelist`. It is applied at exactly two symmetric sites: decompose's
inline tool dispatch, and the shared code `tool` node that serves plan and
execute. Two families stay RAC-**orthogonal** and are always reachable: paths
under `codebase/` (classified via `normalizeToCodebasePath`) and the
`assets/{service,game,gen}/**` pools. Never push this gate into the common
`readFile` / `listFiles` handlers — design and planner jobs have no RAC to honor.
### The user's selection outranks the directory allowlist
A file's **location must never decide whether the job is told it exists.** Four
layers used to re-derive "is this a real file I may use?" from a directory
allowlist, and an attached screenshot lost at every one of them
(`near-loading-brace`). The owners now key off the user's selection or the bytes:
| Question | Owner | Keyed on |
|---|---|---|
| Did the user's slots survive an inferred RAC? | `inferRacWithTools` (`metadata` input → `mergeWithMetadata`) | the FE's `actionMetadata`, additively — inference may ADD, never REPLACE |
| Which UiSource wins a merge? | `pickUiSource(paths, preferred)` + `filterToUiSource` | the source the USER selected outranks the static `ant > figma > handoff` |
| Is this artifact existence-only? | `loadResolvedArtifacts` content sniff → `ResolvedArtifact.kind` | the bytes, in any directory |
| Does it ride along past `task.include`? | `ridesAlongRegardlessOfInclude` | `kind === 'binary'` |
| May the job place it? | `effectiveAssetInventory` | domain pool ∪ attached binaries |
### ❌ Forbidden
- Dropping `actionMetadata.refs` / `context` / `target` / `basis` because the
turn carries no explicit `intent`. Absent intent means "the user did not pick
an action", not "the user selected no files".
- Deciding a UiSource verdict **per slot** when a caller-supplied preference is
in play — `refs` and `context` diverge and the RAC comes out mixed. Decide once
over refs ∪ context, then filter both.
- A new directory allowlist answering "is this a real/placeable file". Sniff the
bytes (`ResolvedArtifact.kind`) or ask the RAC.
- A prompt surface that tells the model a real file it was given is not usable
(the handoff caption's "generate placeholders" vs the `[asset]` stub's "copy
it" — the model obeyed the wrong one and shipped dead placeholders).
```bash
# The infer path must forward the user's slots — dropping this line is the bug.
rg -n "metadata: state\.actionMetadata" packages/ant-cli/src/agents/common/graph/nodes/detect/index.ts # Expected: 1
# The stub decision is the sniff; the prefix list governs TEXT only.
rg -n "isStubLoadedPath\(" packages/ant-cli/src --type ts # Expected: 2 (definition + the one text-branch call)
```
Guards: `tests/detect/metadata-supplement-merge.test.ts`,
`tests/policy/{rac-scope-invariant,asset-surface-boundary,uiSourceExclusivity}.test.ts`,
`tests/prompt/attachment-injection-gate.test.ts`.
Rationale: [`docs/internals/47-attachment-awareness.md`](docs/internals/47-attachment-awareness.md).
---
## Codebase Channel — Existing-Project Awareness
`codebase` is a first-class workspace resource. Two job groups consume it
with different authorities:
| Job group × workspace | RAC slot | Pool load |
|----------------------------------------------------|---------------------------------------|-----------|
| code-anchored (`rev-code` / `explain-code` / `gen-learn`) | `codebaseSlot('ref')` (static) | yes |
| plan/design × existing project | `codebaseSlot('context', { auto: true })` (dynamic) | no |
| plan/design × greenfield | absent | n/a |
The single `codebaseRole` derivation site is
`deriveCodebaseRole(intent, { hasCodebase })` in
`@ant/shared/action-config-matrix.ts`. The single render is the
`templates/jobs/shared/injections/codebase-channel.md` partial, gated on
`{{#if codebaseRole}}`.
`WorkspaceState.hasCodebase` is computed from a disk walk OR'd with the
in-memory index — never memory-only.
---
## UiSource — Three Hard-Exclusive UI Inputs
UI design input is exactly **one** of three sources per RAC. The three values
have different interpretation contracts and must not be mixed.
| UiSource | Path | Meaning | Interpretation |
|-----------|-----------------------|--------------------------------------|----------------|
| `ant` | `visual/ui/ant/` | Design-job output (tokens/assets/spec) | Schema-based |
| `figma` | `visual/ui/figma/figma.json` | Figma file URL reference | Live MCP exploration |
| `handoff` | `visual/ui/handoff/**` | Free-form bundle (HTML/CSS/MD/PNG/JSON) | Observation-only (FPOP) |
The SSOT funnel for the hard-exclusive rule is
`normalizeUiSourceRefs` in `packages/ant-shared/src/canonical.ts`. Every
RAC-creating site goes through it. Mixed RACs throw at the safety nets
(`ArtifactPoolView.uiSource()` / `validateUiSourceExclusivity`).
`figma.json` carries **only the URL + nodeId**. Variable dumps, frame JSON,
and screenshots are never persisted there — the design source is fetched
live via the Figma MCP at prompt time.
---
## Universal Runtime — One JobType, File-Defined Jobs
Custom agents/jobs (the **workspace** project kind) execute on one generic
runtime. The invariants below exist because each was violated once and cost a
debugging session.
### ❌ Forbidden
- **Minting a JobType for a custom job.** A new JobType costs hand-copied
unions in 5+ places; a custom job is *data*, not a code path.
- Forking `customJobRef` or `UniversalTurnMeta` onto a second channel — one
env var each (`ANT_CUSTOM_JOB_REF`, `ANT_UNIVERSAL_TURN_META`), turn meta as
one JSON rather than a CSV per axis.
- **Inferring credential-ness from a value's shape** (the deleted bare-ALL-CAPS
heuristic) — it cannot tell a key name from a legitimate literal, and it
silently killed job starts.
- A `process.env` fallback in credential resolution, or `...process.env` into a
stdio MCP child — either turns a definition into an exfiltration vector.
- Treating checklist items as tasks: no TaskQueue, no kanban cards, no
`billableTaskCount`.
- Offering a path in the `@ctx:` picker that the tool sandbox cannot resolve.
The attachable set is DERIVED from the agent plane
(`resolveUniversalAgentPlanePath` — artifacts ∪ `pipeline-runs` ∪ `_agents` ∪
`_pipelines`, never `sessions`); adding a mount without teaching that
resolver, or the reverse, re-creates the attachable-but-unreadable bug. The
`_pipelines` splitter (`parseUniversalPipelineRef`) IS its whitelist — only
the folder and `pipeline.yaml` resolve; `owner.json` / `availability.json`
are refused on every plane by that one rule.
- Grafting an account-scoped root (agent definitions) into the project file-tree
endpoint. It is cached per project × feature for 24h and the account-scoped
write funnel cannot bust that key — the `_agents` / `_pipelines` subtrees are
picker-side client merges.
- Re-judging the project × jobType gate anywhere other than the truth table,
or letting a definition error crash the worker child instead of answering 400
at accept.
- Silently ignoring a removed yaml key — an author concludes the knob works.
- Clearing armed `universalTurnMeta.context` / `plan` on the way to a dispatch.
An `@ctx` chip is the user's explicit input (the near-loading-brace class: the
selection outranks any policy layer). The Actions-tab Build button owns the
intent slot ONLY — `selectUniversalBuildExecuteContext` composes over the
armed meta and the directive names the attachment
(`universal.buildDirectiveWithContext`); the one reset is post-dispatch.
- **A per-turn pre-classification LLM pass** (intent, tier, or anything else)
before the agent call. Unpinned turns resolve deterministically:
explicit → inherited (clarify continuity) → `general` (there is no catalog
default); the Intent Catalog rendered into the agent prompt — each intent's
`infer.md` criterion — is what informs in-turn self-selection. This was
built twice and removed twice — the latency/cost of a non-streaming call
per turn buys nothing an informed prompt doesn't.
### ✅ Correct
- `jobType='universal'` for every custom job; the definition rides
`customJobRef = "{agentId}/{jobId}"`.
- Capability extension has exactly TWO declaration channels: `mcp.servers`
(MCP servers, stdio/http) and `apis` (declared REST API connections for
systems with no MCP server — baseUrl + `${secret:}` headers + optional
method/path `allow`; the runtime synthesizes `api__{name}__get` /
`api__{name}__request` in-process). Both share the credential store, the
approval gate, and result spooling. API *knowledge* (endpoints, fields,
sequences) is never declared — it is prose in `base/`, intent `prompt.md`,
and `on-demand/**` docs (paths-only index rendered into the system block —
the bodies never inline, so the channel costs no prompt budget). No
per-endpoint tool schemas, no OpenAPI→tools import. The ONE declared
request outside prose is a pipeline's `on.fetch.request` — trigger
CONFIGURATION (the cron expression's sibling) executed by the control-plane
poller, never rendered to a model and never a tool; it rides the same
`buildRestRequest` admission as the tools (doc 46 §2). Its connection is
either a job's `apis` entry (bound) or the trigger's own inline
`connection` — the external entry's shape minus `allow`/`self`, compiled by
the same `compileRestServer`. A trigger is not a capability grant, so a
queue no step calls never earns a job an `apis` entry.
- An `apis` entry takes one of two mutually exclusive forms: external
(`baseUrl` + `headers`) or `self: true`, which targets Ant's own API and
carries NEITHER — the runtime resolves the origin from `ANT_API_URL` and the
bearer from the token minted at accept. It is the only `apis` form a builtin
agent may declare (same reason MCP is forbidden there: a shipped definition
assumes no install URL and no registered credential).
- **A definition's `allow` list is not a security boundary** — the definition is
user-editable, so the pin is never scoped per definition. For a self entry the
boundary is `createSelfApiScopeGuard`, mounted after authentication on `/api`
(ant-api) and on the realtime server. A `scope: 'self-api'` token reaches
**`/definitions` and nothing else** — the scoped-template family — whose two
resources carry deliberately OPPOSITE polarity:
- `/definitions/agents` — **allow-except**: the whole resource is authoring,
minus `promote` / `editors` (authority spread) and `import` /
`files/upload` (they skip `gateDefinitionSave`).
- `/definitions/pipelines` — **deny-except**: most of that resource is
OPERATIONAL, so only the authoring shapes are listed (`GET|POST` on the
root, `GET|PUT|DELETE` on `:id`, `GET :id/permissions`,
`POST preview-fires`, `GET activatable-projects`) and everything else —
present or added later — is refused. `enable` / `disable` / `activate` /
`deactivate` / `run-now` / `promote` / `editors` / `approvals` / `runs` are
a person's decisions; a job drafts, a person publishes. Never invert this
polarity: an allow-except list here would admit every route added after it.
A `:id` rule must exclude its resource's reserved literals (`preview-fires`,
`activatable-projects`, `approvals`, `runs`) — Express disambiguates them by
registration order, the guard matches independently, so
`GET /definitions/pipelines/approvals` would otherwise ride the `:id` shape.
The realtime server has no `/definitions` surface, so the same guard refuses
the claim there wholesale — a job-minted token must not open its owner's SSE
stream or `/bridge/*`. Absence of the claim is an ordinary session, never a
pin. Minting stays in the process holding the JWT private key (C-001).
- **Definition writes have one funnel**: `PUT /definitions/agents/:agentId/file` →
`gateDefinitionSave` → `loadCustomJob`. A job authors definitions by calling
it (the builtin `agent-builder`), never by writing the files directly — which
is also why `run_command`'s containment check runs on every plane, not only
where the `codebase/` prefix rule applies. Pipelines are the same shape one
resource over — `POST|PUT /definitions/pipelines` under the same pin — held
by the builtin `pipeline-builder`. The two builtins split one boundary:
`agent-builder` authors what an agent DOES and FILTERS calendars and
cross-intent run order out (doc 44), its `allow` naming only the agents
resource; `pipeline-builder` composes a finished agent's intents into a
schedule, its `allow` writing only the pipelines resource (agents GET-only).
Both lanes are pinned in `tests/customAgents/builtin-agents.test.ts`. A
user-scope pipeline-authoring agent works identically — the pin admits by
`declaresSelfApi`, which reads the definition, not the scope, so a
user-scope agent declaring a self entry gets the same token a builtin would.
- **HTTP groups name a KIND, not an owner.** `/api/definitions/**` is the
scoped-template family (`user` | `org` | `builtin` roots, closest-wins,
promotable, project-independent, one shared `orgAclStore.ts`) and holds
`agents` + `pipelines`; `/api/credentials/**` holds `{org, user}`-keyed secret
stores. A resource joins the family it belongs to — **"the bare name was free"
is not a reason to mount at the root**, and that ad-hoc rule is exactly how a
template ended up spelled `/api/account/agents` in one place and
`/api/pipelines` in another. `/api/agents` is the PUBLIC canonical job-agent
catalog and is a different concept from a custom agent definition. The full
table, including what is still bare, is in
[docs/reference/api.md](docs/reference/api.md#grouping-rule--by-kind-not-by-owner).
- `decideProjectJobGate` (`core/customAgents/universalContainer.ts`) is the one
bidirectional truth table; enforcement is HTTP 400 at job-accept.
- `${secret:KEY}` (`MCP_SECRET_REF_PATTERN`) is the only credential marker;
everything else is a literal. `validateMcpServers` in `@ant/shared` is the one
rule set, with three failure shapes (throw / 400 / form-disable).
- `buildStdioChildEnv()` allowlist for stdio children; `McpConfigError` →
`config_invalid`, never `process_crash`. Connect failures are fatal on the
UNATTENDED lane only (pipeline/scheduled — `failFast`); an attended turn
DEGRADES per server and runs, with the failure as a fact the agent explains
(the `Capability Status` band). `core/customAgents/connectionReport.ts` is
the single owner of that report's shape and every rendering — never add a
second renderer, and never re-derive the lane anywhere but the runner's
`failFast` rule (doc 44).
- Phase-node blindness applies here too: the universal graph must not learn
`task.type` or execution tiers — it has neither.
- **Universal's leftover work is an unsealed TURN, not a task queue.** Resume
re-runs the interrupted instruction on the saved transcript, so `canResume`
and its KIND come from one owner — `resumeGranularityOf`
(`mid-graph` | `turn` | `null`) — and `isMidGraphResumable` keeps its narrow
"a checkpoint exists" meaning. The resume request carries NO definition ref:
`resolveUniversalResumeTarget` recovers it from the job's own durable records,
because a client-held ref names the composer's current selection rather than
the paused pair. Never word a `turn` resume as continuing from where it
stopped, and never let a decided refusal reach the client as a code-less 500.
- **Hooks follow the act, not the label.** An intent that also answers
questions or audits declares `hooks.arm: on-write` — its contract arms only
once the turn writes anything (a draft in artifacts included), so a turn that
only reads ends clean; a deliverable intent keeps the default `always`. An
unpinned (`general`) turn that performs an intent's `action:` hook ADOPTS
that intent's contract. On a pinned deliverable turn the agent's
`<contract-deferred>reason</contract-deferred>` is the ONE machine-readable
"this turn owes nothing / cannot deliver" (honored only attended + no write
evidence), and an unmet contract ESCALATES (`universal_stop_hook_unmet`) on
the unattended lane only — attended carries it in the seal to the next
message (doc 44 hooks rule 4). Never author a hookless "read-only" twin intent to get
a turn that does not owe a write — read-only is the `@plan` turn, which is
machine-enforced; a prose "do not write" is not. A review that LEAVES a
record is not that twin: the builders' `review` intent owes
`review-report/*.md` through an `artifact:` hook with the default arm, and
its offline twin for an external agent is `docs/guides/builder-handoff/`
(channel deltas only — the shipped prose stays the one contract, guarded by
`tests/policy/builder-handoff-binding.test.ts`). The clone-less form is the
GENERATED bundle (`GET …/handoff/{jobId}/{intentId}`, `definition handoff`)
composed by `builderHandoff.ts` from the delta doc + the definition files;
never hand-edit a bundle, never commit one.
```bash
rg -n "process\.env" packages/ant-cli/src/core/customAgents/McpCredentialResolver.ts # Expected: 0
rg -n "ExecutionTier|executionTier" packages/ant-cli/src/agents/universal # Expected: 0
# The attachable set has ONE owner; the gate and the band both go through it.
rg -n "resolveUniversalMergedPath" packages/ant-cli/src/core/scheduling packages/ant-cli/src/agents/universal # Expected: 0
# Reserved mount names come from @ant/shared (UNIVERSAL_AGENTS_DIRNAME / UNIVERSAL_PIPELINES_DIRNAME), never literals.
rg -n "'_agents'|'_pipelines'" packages/ant-cli/src packages/ant-ui/src # Expected: 0
# The pin is one rule, mounted whole-surface on each cookie/bearer server — never re-judged per route.
rg -n "createSelfApiScopeGuard\(" packages/ant-cli/src # Expected: 3 (definition + api mount + realtime mount)
rg -n "ANT_THREAD_ID|threadPaths|getAgentThreadPath" packages/*/src # Expected: 0
# The resume verdict has ONE owner; nobody re-derives it from the job type.
rg -n "isMidGraphResumable\(" packages/ant-cli/src packages/ant-shared/src # Expected: 2 (the definition + its ONE call, inside resumeGranularityOf)
# A universal session path has ONE run-aware owner (getUniversalSessionFilePath); the runtime and the scheduler never compose the shared one.
rg -n "\bgetSessionFilePath\(" packages/ant-cli/src/infrastructure/scheduling packages/ant-cli/src/agents/universal # Expected: 0
```
Guards: `tests/customAgents/{custom-agent-loader,builtin-agents,universal-container,universal-tool-policy,universal-prompt-injection,universal-checklist,universal-turn-context,universal-mcp-runtime,mcp-credential-store}.test.ts`,
`tests/lifecycle/dismiss-route-branches.test.ts` (resume routing + typed refusals),
`tests/composition/sigterm-interruption.test.ts` (the granularity table).
Full rationale: [`docs/internals/44-universal-job.md`](docs/internals/44-universal-job.md);
MCP orchestration & capability-server contract:
[`docs/internals/45-mcp-orchestration.md`](docs/internals/45-mcp-orchestration.md).
---
## Authorization Answers Whose, Never How Much
**An authenticated route is not a budgeted one.** Every gate on
`/jobs/:jobId/continue` — access, approval, membership, credit, canonical-project,
pipeline-ownership — proved WHOSE session it was, and none of them bounded the
work: the handler then read that session, unshifted another directive, and wrote
it back with a raw `fs.writeFileSync()`, outside the byte budget every reader
enforces. The same split produced `chat/job-error` (no schema, no cap, no rate
limit) and a job-history scan that parsed 5,000 session files into one response.
Three rules; each later one is why the one before it kept failing:
- **Each authenticated route carries its own field caps, request rate, and
response-materialization budget.** A per-item cap is not a per-request bound.
- **A seam is adopted by FILE, not by call name.** `atomicWriteFile(` was the
guard, so three writers reached the same session files by a different shape and
no test failed. Enforce the offense as "this path reached a write that is not
the seam", whatever that write is spelled.
- **Seam adoption is enforced in TYPE space, not by name greps.** Four audit
rounds keyed the guard on names (literal paths → call names → variable names)
and each round a differently-spelled caller slipped past — names are
re-spellable by construction. The closed form is a branded type with a single
mint (`boundActionMetadata` → `BoundedActionMetadata`) that every consumer
signature between an ingress and a durable/broadcast/env sink requires: a new
typed ingress fails `pnpm typecheck`, not a regex. Greps survive only for what
the compiler cannot see — brand fabrication (`as BoundedActionMetadata`, a
finite spelling) and the `any` trust boundaries (HTTP `req.body`, queue/env
replay), each of which pairs with a RUNTIME re-check calling the same mint.
An open-shaped object (`.passthrough()`) is budgeted by its **whole serialized
size**, never by field enumeration — an unknown field is outside a field-cap
model by definition.
### ❌ Forbidden
- Writing a session JSON by any route other than `writeSessionBounded()` — raw
`fs.write*`, or a hand-rolled tmp+rename. A read-modify-write passes
`{ expect: sessionWriteGuardOf(text) }` built from the bytes it already read;
it does not re-read, and it does not add a lock.
- Passing action metadata to a durable/broadcast/env consumer as a raw object —
the consumers take `BoundedActionMetadata`, and the only mint is
`boundActionMetadata()` (typed 413 / typed job failure on over-budget).
- REFUSING an append to bound a JSONL log. Readers already serve only the newest
window, so the fix is retention (trim to that window — observably lossless),
never a rejection that stops chat working. The ONE exception is a single line
over `JSONL_LINE_MAX_BYTES`: appended, it swallows the whole tail window and
every bounded reader returns zero lines (the log goes blank), so refusing that
line — before append AND broadcast — is the only observably-lossless outcome.
- THROWING when an enumeration budget runs out on a display-only path. Degrade
(less folder compression, a `truncated: true` sibling key); never fail a request
that would otherwise have succeeded.
- Registering a cross-pod lock on one side only. The API process and the job-runner
child append to the same logs on the same mount.
- Capping a field that is serialized into a durable line by its per-field length.
Cap the SERIALIZED value — a join or a `JSON.stringify` amplifies past it.
- A guard that enumerates the routes someone remembered. Enumerate the SET.
- Letting a parser's own limit breach reach the framework's default error
handler. multer aborts with `next(new MulterError(...))`; with no handler that
became an HTML 500, so a folder upload the budget legitimately refused was
indistinguishable from a crash and the FE could only say "upload failed".
- Choosing a multipart `fields` / `parts` cap independently of `files`. Every
lane pairs each file part with one `relativePaths` field, so `fields: 50`
refused the 50th file and the advertised count was unreachable — the caps must
be DERIVED from `files` or the number the client batches on is a lie.
### ✅ Correct
- `writeSessionBounded()` sheds in a fixed order — snapshots → conversations →
diagnostics → oldest `runs[]` — and only then refuses, leaving the previous valid
file untouched. The resume core (`taskQueue` / `currentTask` / `completedTasks` /
`interruption` / `jobId`) is never shed.
- Count and reserve in ONE step: `StateStorePort.reserveSlot` (Redis ZSET + Lua).
A read-then-compare admits N callers past an N-1 cap — SSE slots (M-005),
pipeline concurrent runs (L-031), and uploads all share that shape.
- Asymmetric lock failure where the two operations have asymmetric stakes: an
append is best-effort (never lose a line to a slow lock), a whole-file rewrite
requires the lock (never race one silently).
- A per-account share of any pod-local ceiling, released on the same
`finish`/`close`/`aborted` the pod counter uses — a second lifetime is a second
leak.
- The chat.jsonl append seam owns two field-agnostic invariants: no single line
past `JSONL_LINE_MAX_BYTES` (typed refusal, no SSE echo of a line no reader
could return), and a streaming heal that drops pre-cap oversized lines without
materialising them when retention finds zero complete lines in the window.
- `boundedMultipartUpload(upload, field, deps)` is the ONE way to mount a
multipart route — it composes the admission gates, multer, and
`refuseMultipartError` (typed 413/400 `{code, error, message}`, never
`sendErrorResponse`, whose envelope carries no `code` and is genericised in
production). Adoption is a property of the call, not of what an author
remembered: a bare `upload.array(` under `routes/` is the offense.
- A client that would exceed a documented request cap BATCHES to it rather than
discovering the wall: `@ant/shared/upload-limits` is the one home for the caps
a client must act on, so `UPLOAD_MAX_FILES_PER_REQUEST` is simultaneously the
FE batch size and the BE `files` cap and neither side does margin arithmetic.
The driver (`runUploadBatches`) is strictly sequential — a fan-out would 429
itself against the cluster-wide per-account slot, and sequencing is what makes
"a destructive field rides batch 1 only" a guarantee rather than a race for
the two replace lanes that `fs.rmSync` before writing.
```bash
# The write seam is a property of the file, not of one call name.
rg -n "fs\.(writeFile|writeFileSync)\(\s*sessionPath" packages/ant-cli/src # Expected: 0
# Every chat POST carries both gates.
rg -c "chatRateLimiter" packages/ant-cli/src/periphery/adapters/http/routes/chat.routes.ts # Expected: >= 5
# The actionMetadata brand has ONE mint; a cast is the only spelling that bypasses the compiler.
rg -n "as (unknown as )?BoundedActionMetadata" packages/ant-cli/src --type ts # Expected: 1 (the mint)
# No route mounts multer directly — every multipart lane composes the wrapper.
rg -n "upload\.(array|single|fields)\(" packages/ant-cli/src/periphery/adapters/http/routes # Expected: 0
```
Guards: `tests/policy/contained-io-adoption.test.ts`,
`tests/policy/resource-admission.test.ts`, `tests/http/resource-admission.test.ts`,
`tests/security/session-namespace-bounds.test.ts`. Rationale:
[`docs/internals/security-posture.md`](docs/internals/security-posture.md) Axis 7.
---
## An Authenticated Route Is Not an Approved One
**Account approval is an identity verdict, so it bounds the whole authenticated
surface — never a list of routes.** `UserRecord.approvalStatus` used to be six
hand-placed pre-flight calls at compute-start handlers (job start/learn/resume/
continue, chat, team create). That blocked starting agent work and nothing else:
a `pending` account still created and deleted projects, uploaded files, booted
preview/deploy children, attached a GitHub PAT, wrote agent definitions, drove a
live IDE pod, opened every SSE stream, and minted a 90-day desktop token. The
list WAS the bug — it grows by whatever the next author remembers.
### ❌ Forbidden
- Re-judging approval inside a route handler. The surface guard has already
answered; a second owner drifts (the `teams.routes.ts` copy had already
diverged to a different fail-open posture than the other five).
- Re-listing the public paths as approval exemptions. The guard keys on
`req.user`, which `createJwtAuthMiddleware` sets only for non-public requests,
so the exemption is DERIVED from `PUBLIC_PATHS`. A second copy drifts.
- Putting an approval claim in the JWT. The cookie lives days and the desktop
token 90; an admin approving would not take effect until re-login, which is
precisely the operator workflow.
- A process-local TTL cache of the verdict. It re-introduces a second answer
source for a decision whose whole point is immediacy — a `denied` account
keeps working for the TTL.
- Mounting on ONE plane. Express is not the only way in: the `/ide/*` proxy is
served before `setupAuthentication` and never calls `next()`, and the bridge
WebSocket upgrade bypasses Express entirely.
### ✅ Correct
- `createRequireApprovedAccount()` mounted whole-surface on every server that
authenticates a cookie or bearer, plus the `/ide/` proxy lane; `checkApproval`
stays the single read of the port and the single fail-open posture.
- Fail-OPEN on a repository error. Redis is the whole system's dependency, so a
blip that flipped this closed would convert an outage into a total lockout of
every approved user, reported under a misleading pending code.
- `/admin` exempt: it carries a strictly stronger env-authoritative gate
(`isSuperAdminEmail`), and `setUserApproval` can stamp a super admin `denied`
while `syncSuperAdmins` only re-approves at boot — gating it bricks the
operator out of the screen that undoes the mistake.
- FE: one state-driven branch (`selectShowApprovalGate`) replaces the app shell,
and `selectIsAuthBlocked` parks every protected fetch, so the screen does not
sit in front of a 403 storm.
```bash
# One rule, mounted on each plane that admits an identity — never re-judged per route.
rg -n "createRequireApprovedAccount\(\)" packages/ant-cli/src # Expected: 5 (definition + api + ide + realtime + preview)
# The port read has ONE owner; its callers are the three planes, not handlers.
rg -n "checkApproval\(|getUserApproval\(" packages/ant-cli/src/periphery/adapters/http/routes/*.routes.ts # Expected: 0
```
Guards: `tests/policy/resource-admission.test.ts` (mount order + the SET, read
from the codebase so a fifth server cannot skip it),
`tests/billing/approval-capability-seam.test.ts` (the guard's decision table),
`tests/auth/lifecycle-guard.test.ts` (FE truth table + branch ordering).
---
## Untrusted Content and the Control Plane Are Different Origins
**A browser origin that serves user-authored content MUST NOT also answer a
cookie-authenticated control-plane API.** `ant-preview` does both jobs — it serves a
public deploy's build output and a user's own dev server, and it exposes
`/projects/*`, which starts previews and writes a feature's `.env`. On one origin,
script inside a deployed SVG or HTML page runs same-origin with that API and drives
it with the viewer's session. The session cookie is `HttpOnly`, which does not
help: the browser attaches it anyway.
### ❌ Forbidden
- Mounting any control-plane route on the content listener (`this.contentApp`).
- "Fixing" this with an SVG/HTML filter, a blanket CSP, or by stripping cookies on
the proxy hop to the upstream. None of them addresses the sink, which is the
browser's own origin model.
- Comparing origins by **hostname**. `isSelfOrigin` compares scheme + host + port;
a hostname-only test silently re-merges the two listeners.
- Accepting a cookie-authenticated state change whose `Sec-Fetch-Site` is
`same-site` (that is precisely the content listener) — only `same-origin` /
`none`, or an exact-match registered frontend origin.
- Admitting a request on `Sec-Fetch-Mode: navigate` / `Sec-Fetch-Dest`. A GET
navigation carries no `Origin`, and in a split-host deployment its
`Sec-Fetch-Site` is `same-site` — indistinguishable from attacker content. The
`/ide/*` iframe is admitted by a short-lived capability minted through a
CSRF-guarded POST instead; see
[`docs/internals/23-cloud-ide.md`](docs/internals/23-cloud-ide.md).
### ✅ Correct
- Content on `ANT_PREVIEW_CONTENT_PORT`, control plane on `PORT`; the process
refuses to boot if they are equal.
- `createSameOriginGuard()` after cookie-parser on every server that authenticates
by cookie. `Authorization: Bearer` callers are exempt — a bearer token is not
ambient.
- Body parsers mount AFTER authentication: an unauthenticated request must not make
the process parse a 50 MB body before it is told 401.
```bash
rg -n "contentApp\.(get|post|put|delete)\('/(projects|admin)" packages/ant-cli/src # Expected: 0
rg -n "sec-fetch-(mode|dest)" packages/ant-cli/src/periphery/adapters/http/middleware/sameOriginGuard.ts # Expected: 0
```
Guards: `tests/http/preview-origin-split.test.ts`, `tests/http/same-origin-guard.test.ts`,
`tests/http/ide-gate-admission.test.ts`, `tests/cors/cors-matrix.test.ts`. Rationale: [`docs/internals/security-posture.md`](docs/internals/security-posture.md) Axis 5.
---
## Child Process Boundaries — env profile, credential scope, OS identity
Preview, deploy and code-job children run **user-authored code**, and their
stdout/stderr is streamed back to the requester. Four separate rules, each violated
once:
1. **Env profile.** `composeChildEnv()` (preview/deploy) honours
`ANT_PREVIEW_ENV_PASSTHROUGH`; `composeCommandChildEnv()` (code-job
`run_command`) honours nothing. An operator naming a host variable so a dev
server boots did not consent to it reaching every LLM-chosen command and its
chat transcript.
2. **Namespace denial is by NAME, never by value shape.** The credential-marker
list is a name test, and a live credential need not look like one —
`ANT_REDIS_URL` carries the data plane with no `TOKEN`/`SECRET`/`AUTH` in it. The
inherited/passthrough path refuses the whole `ANT_*` namespace plus bare
connection-URL names. Project `.env` overlays are a different channel and are
unaffected. Do **not** add value-shape heuristics (see the universal-runtime
section for why that was deleted once already).
3. **Credentials are scoped to the step that needs them.** A user's PAT reaches the
`--ignore-scripts` dependency-FETCH pass only; the lifecycle pass re-runs the
install without it. Installs that cannot use `GIT_CONFIG_*` at all
(python/rust/java) never receive it.
4. **The filesystem a child sees is a mount namespace, not the pod.** Env
scrubbing and the UID drop bound what a child learns from its own process;
neither bounds the disk — a child under any UID walked `/vault`, `/etc` and
every other tenant's workspace, and one `cp` moved a Vault-injected secret
file into the requester-visible artifacts (2026-09 report). Every
user-authored spawn goes through ONE funnel, `spawnUserChild()`
(`core/config/childSandbox.ts`; `wrapCommandForUserChild()` where an SDK owns
the spawn), which composes identity gate → UID drop → bubblewrap in that
order: the call site names the tenant roots (`sandbox.rwRoots` / `roRoots`),
the system toolchain is read-only, and what is not bound does not exist. The
path parsers (`detectReadPathViolations`) stay as guardrails; the namespace
is the boundary. `ANT_CHILD_SANDBOX` is on by default in cloud and
fail-CLOSED (non-Linux, no `bwrap`, namespaces refused → the spawn is
refused); a deployment that cannot sandbox says `off` explicitly. Two
corollaries: `CommandOptions.sandbox` is required in TYPE space, so a caller
that cannot name the boundary does not compile; and `kill <server_pid>` is
served by the `run_command` handler against the handle it holds, because a
later command's PID namespace cannot see an earlier command's server.
The funnel is also where `childSpawnIdentity()` is spread, so a deployment that
grants the privilege runs those children under their own UID — a same-UID child
can read `/proc/<service-pid>/environ` whatever the composed env says.
```bash
rg -n "composeChildEnv\(\)" packages/ant-cli/src/periphery/adapters/command # Expected: 0 (command profile)
# User code has ONE spawn funnel; an identity spread into spawn options is a site that skipped it.
rg -n "\.\.\.(childSpawnIdentity|credentialedAcquireIdentity)\(\)" packages/ant-cli/src --type ts # Expected: 0
rg -n "wrapCommandForChildIdentity\(" packages/ant-cli/src --type ts # Expected: 2 (definition + its one call, inside wrapCommandForUserChild)
```
Guards: `tests/policy/credential-isolation.test.ts` (funnel adoption, image
launchers), `tests/security/child-sandbox.test.ts` (binding rules, refusals,
live invisibility), `tests/preview/installCommand.test.ts`.
---
## Project / Feature Lifecycle
Project and feature lifecycles share three policies:
1. **`repoType` defaults to `'cloud'`.** `repoType: 'local'` is opt-in only,
set explicitly through the wizard's advanced options. Auto-mapping from
`userContext` (`local:local` vs cloud) is forbidden — that pattern caused
path collisions in past regressions.
2. **`deleteProject` runs a 5-step cascade**: cancel jobs → IDE pod
cleanup → preview pub/sub ack → Redis state cleanup → fs.rm verification.
Skipping any step risks leaking EFS handles or stale workers.
3. **Cross-process cleanup uses Redis pub/sub** (`ant:lifecycle:cleanup:*`),
not in-process method calls. Each process must listen for and ack
cleanup requests.
`renameProject` shares steps 1–4 with `deleteProject` via the
`stopProjectRuntime` SSOT helper.
---
## Code Style
- **TypeScript strict mode**.
- **ESLint + Prettier**. Format on save.
- **Console logs use emoji prefixes** (`📄 [DocGen]`, `🔧 [Tool]`).
- **Comments are lean.** Don't translate the code line-by-line. New
comments only for non-obvious invariants, external contracts, or trade-offs
(one sentence). JSDoc for public APIs and `@deprecated` markers — not
every function. A patch where comments outnumber executable lines is too
comment-heavy.
- **Imports are absolute or workspace-relative**. Don't reach across
packages with `../../../`.
---
## Writing Tests & Regression Guards
The suite is large (≈640 files / ≈6,900 cases, ~35s) and that size is fine —
it runs fast and 70%+ of commits touch it. What degrades it is a specific
authoring habit: turning each incident into a new file that pins prose rather
than behavior. These rules exist to stop that.
### Where tests are gated
| Surface | Gate |
|---|---|
| `packages/ant-cli/tests/**` | `pnpm test:cli` + `pnpm typecheck:tests` (CI) |
| `packages/ant-ui/tests/**`, `src/**/__tests__/**` | `pnpm --filter @ant/ui test` (CI) |
| `packages/cloud/tests/**` (ant-cloud) | `pnpm test:cloud` (ant-cloud PR CI) |
| `tests/e2e-mock/**` | `pnpm test:e2e` — needs a live mock server, excluded from `test:cli` by design |
**The build does NOT run tests** and no `prebuild` hook should be added — CI is
the only gate. Test sources are excluded from `packages/ant-cli/tsconfig.json`
because it ships into the runtime image; `tsconfig.test.json` is what
typechecks them. Never add test globs to the shipped config.
`pnpm typecheck:tests` is **blocking in CI** — keep it at zero. It was added
after tests went un-typechecked long enough to accumulate 185 errors across 57
files (stale import paths, task literals missing required fields, `interface X
extends BaseTask` from before that type became a union, spies with too-small
declared arity, and fields already deleted from the types).
### ❌ Forbidden
- **Pinning prompt prose.** `expect(rendered).toMatch(/ONE store instance/)`
locks an English sentence, so improving the wording fails the build. Assert
the **gate** instead: does this partial get injected when the gate is on, and
not when it is off? If the rule can't be expressed as a gate truth table, it
isn't a contract — don't test it.
- **Testing a gitignored file.** `CLAUDE.md` / `.cursorrules` are gitignored, so
a test asserting their prose `it.skip`s in CI and on every fresh clone — it
looks green while checking nothing. Doc-prose sync is not a test's job.
- **A new file per incident.** Add a row to the existing policy test for that
axis. Codename-named files (`regression-<codename>.test.ts`) fragment one
invariant across many near-duplicate regexes that then drift.
- **Duplicating a rule in CI shell and in a test.** One owner. Prefer the test —
it can strip comments and reason about structure; a `grep -vE` heuristic can't.
- **`expect(true).toBe(true)` as a soft skip**, or asserting a constant against
its own literal. If the case needs env state, stub it (`vi.stubEnv` +
`vi.resetModules()` + re-import) so the path actually executes.
- **Reaching into another package** (`import … from '../../../ant-ui/src/…'`).
FE behavior is owned by the ant-ui suite, BE by ant-cli.
### ✅ Correct
- Table-driven policy tests: one file per axis, one row per case.
- Tombstones (asserting a deleted file stays deleted) are valid **in the
deletion commit**. They accrue no signal afterwards — prune them once the
removal is a year old and nothing references the symbol.
- Fixtures a test generates belong in `.gitignore`, not in git. A tracked file
that a test rewrites on every run produces a spurious diff forever.
- When a test and the source disagree, decide which is stale before editing.
A test pinning a retired model id or a renamed field is usually the stale
one — but confirm against the commit that changed the behavior.
---
## Prompt Engineering
Rules for authoring Handlebars prompt templates under
`packages/ant-cli/src/core/prompt/templates/`.
### Enforcement status (read first)
Not all policies below are equal. Some fail a build when broken; some are
only reviewer judgement. Treat that difference as load-bearing — a rule with
no automated guard is a **guideline**, not a contract, and must not be cited
as if it were one.
| Policy | Enforced? | Guard |
|--------|-----------|-------|
| MECE / locality / partition gates | ✅ CI | `domain-branching-locality`, `domain-vocab-locality`, `domain-overlay-locality`, `domain-surface-boundary`, `asset-surface-boundary`, `basis-partial-invariant`, `motion-locality`, `service-virtualization`, … |
| WHAT / HOW split (§1) | ⚠️ Guideline | reviewer judgement (transitional — legacy violations tolerated) |
| FPOP (§4) | ⚠️ Guideline | reviewer judgement only — no CI lock |
| SBS (§5) | ⚠️ Guideline | soft sanity grep only — not a build gate |
| Artifact-language ladder (§3) | ⚠️ Guideline | prompt prose; only the inverse is gated — `builtin-agents` (shipped definitions stay Latin-script) |
The policies below are four orthogonal failure-mode axes: **specificity =
activation scope** (SBS, FPOP "Universal over Specific"), **single home /
collectively-exhaustive partition** (MECE, WHAT/HOW), **falsifiable constraints**
(FPOP "Observable", "Constraints over Instructions"), and **self-contained
runtime** — a prompt must not reference internal vocabulary the model was never
given (acronyms, decision IDs, incident codenames). That last axis and "no rule
without a guard" are unenforced: conscious guidelines, not contracts.
### 1. WHAT / HOW separation
| Prefix | Role | Content |
|--------------|------|--------------------------------------------|
| `base*.md` | WHAT | Context, data, current state, dynamic interpolation |
| `rules*.md` | HOW | Rules, formats, constraints, prohibitions |
For new or substantively rewritten files, do not put `⚠️ You MUST` /
`DO NOT` directives in `base*.md`, and do not put `{{{interpolations}}}` in
`rules*.md`.
### 2. Directory layout
```
templates/
├── domain/{d}.md workspace-level domain identity (service / game)
├── basis/ tier-gated content + shared partials
├── jobs/{job}/
│ ├── base/{system,user,injections}/ job-level shared blocks
│ ├── domain/{d}.md job × domain overlay
│ ├── basis/ job × tier overlay
│ └── nodes/{node}/
│ ├── {base,rules}.md default
│ └── variants/{v}/{base,rules}.md variant-specific
├── jobs/shared/nodes/{node}/variants/{v}/{base,rules}.md cross-job
└── infra/ infra-level partials (compaction, etc.)
```
Templates are auto-registered as Handlebars partials by `initPartials()` at
server startup. **Files under `templates/basis/**` are intentionally not
registered.** Use `_*-private.md` named partials in `jobs/...` if you need a
private partial inside a basis-adjacent file.
### 3. Language and platform neutrality
Prompt **source shipped with Ant** is English only — everything under
`core/prompt/templates/**` and the builtin agent definitions under
`core/data/agents/**`. No project-specific examples (`Hero.tsx`, `page.tsx`),
no platform-specific terms (`React`, `Tailwind`, `Next.js`). Use generic,
platform-neutral wording (`component`, `container`, `element`).
Ant supports frontend / backend / fullstack across multiple languages.
Prompts must not assume a stack.
**This rule does not reach user-authored universal definitions**
(`.ant/agents/**`). Those are one team's data, read and maintained in the agent
settings screen by the person who owns them, and full of proper nouns with no
English form — so their prose follows the requester's language. The universal
runtime states the precedence once, in
`templates/jobs/universal/nodes/agent/rules.md` (Output Channel): an explicit
user instruction → the definition's stated convention → the language of the file
being revised → the language of the user's request. Rungs 2 and 3 above 4 are
what keep an existing file from flipping language on its own. Structural tokens
(ids, yaml keys, paths, tool names, `${secret:}` refs) never localize.
⚠️ Guideline, not a contract — it is prompt prose and pinning it would violate
the no-prose-pinning rule. What IS guarded is the inverse: shipped definitions
carry no non-Latin script (`tests/customAgents/builtin-agents.test.ts`).
Do not re-derive the authored language from `state.language` — it is a binary
ko/en UI locale and cannot express any other language.
### 4. FPOP — First-Principles Observation Prompting — guideline (not CI-enforced)
State observation targets and constraints as **principles**, not as concrete
examples or methods: principles over examples, what over how, observable over
assumed, universal over specific, constraints over instructions, and an explicit
⚠️ reminder for a blind spot the model reliably misses. Concretely — "each
container decides its direction independently", not "the footer is a column";
"if it is not observed, do NOT add it", not "add an overlay".
### 5. SBS — Scope-Bound Specificity — guideline (soft sanity grep only)
**A fragment's required abstraction level is bounded by its activation scope.**
Gated templates (techTier / intent / taskType / mode / role / artifact-presence)
MUST be specific along the gate's axis; always-on templates MUST stay universal.
`basis/techTier/framework/nextjs.md` MUST name "Next.js" — the gate is the entire
reason the file exists, so citing "Universal over Specific" against a gated file
to strip its discriminator is itself an SBS violation.
Run both checks on every paragraph: is it specific along **this file's** gate
(if not, lift it to a less-gated location), and is it specific along **any other**
axis (if so, that is scope creep — lift it out). A compliant paragraph is
specific exactly along the gate and generic everywhere else. Corollary: if you
cannot tell which variant a paragraph came from with the path hidden, the variant
is SBS-empty.
---
## Cross-Package Contracts (`@ant/shared`)
`@ant/shared` is the single source of truth for every type that crosses BE↔FE —
job classification (`JobType`, `DecomposableJobType`), task queue state
(`BaseTask`, `KanbanData`, `TaskStatus`), SSE payloads (`WorkflowRealtimeState`),
interruption metadata, detection types (`InferredAction`, `Mode`, `IntentGroup`),
and RAC / tier types (`ResolvedActionContext`, `TechTier`, `ResolvedArtifact`).
The full inventory is [docs/reference/shared-types.md](docs/reference/shared-types.md).
Adding a shared type is a **contract change**: land it with both BE and FE
consumers in the same PR where possible, and add a regression test in
`packages/ant-cli/tests/` that exercises the new shape. `@ant/shared` also ships
runtime code (canonical paths, the action-config matrix, tier matrices) — after
editing that, run `pnpm --filter @ant/shared build`.
---
## Where to Read Next
The regression-grade rationale behind every rule above — incident-driven
invariants, enforcement greps, and the test that guards each one — lives in
[`docs/internals/`](docs/internals/). Read it before touching the graph, the
prompt builder, or any SSOT function. See the [Quick Map](#quick-map) for
everything else.