Restricted Agents: How Ysbuild Authors Atomic Specs Under ValidKeep Rules

ysbuild turns one LLM into many narrow ysbuilders. Each role (rx, cx, lx, oqtest, code, and others) receives a ten-section prompt with strict upstream/downstream blindness mirroring the assurance profile trace graph. It accelerates authoring for Yttrigen teams; it does not replace npx validkeep verify. Role names map to atomic files types explained in the atomic model. Ysbuild is optional Yttrigen in-house tooling; ValidKeep verify is the common gate for all authors.

Role inventory

Ten-section prompt anatomy

Each ysbuild turn assembles ten sections (from the ysbuild profile header):

1. GENERAL INTRODUCTION: architecture doc + assurance YAML (cached when cache: true)
2. SYSTEM INSTRUCTION: per-role static prompt
3. UPSTREAM SOURCES: peer specs from authoring context
4. UPSTREAM SIDECARS: filecars for upstream sources
5. TRACE BINDINGS: tracecars scoped by profile rules
6. ASSIGNED ARTIFACTS: files this role may create or edit
7. ASSIGNED SIDECARS: filecars for assigned artifacts
8. MODULE SURVEY: review context inventory (when non-empty)
9. MESSAGES RECEIVED: consumed ysbuild ledger inbox
10. OUTPUT CONTRACT: patch format and disposition rules

Trace rules resolve from the assurance profile at load time, not hard-coded in prompts alone.

Scope keys: peer, children, tree

These map to assurance profile trace scopes. A peer role sees sibling atoms in the module directory; children roles author downward; tree roles see the module subtree for tests and code while remaining blind to forbidden upstream nodes.

Restriction examples

• oqtest blind to $L_x$: tests prove $O_x$ via $C_x$, not implementation shortcuts
• pqtest blind to $C_x$ business prose: focuses on $L_x$ resilience probes
• lx blind to OQ/PQ artifacts: design does not chase test scripts

Same story as methodology articles, but from the authoring angle. See OQ and PQ articles linked below.

Gapfield: disagreeing professionally with upstream

When a ysbuild agent cannot finish without upstream change, it emits a gapfield block instead of silently over-reaching or inventing trace joins. Example: lx finds $C_x$ promises a timeout $R_x$ never authorized. The agent cites rule IDs and recommends rx or cx as owner rather than patching blind roles.

Blocked turns (no file patch) are valid. npx validkeep verify may fail until joins balance; that is desirable. Gapfield pushes work upward; anti-reach (below) stops downward tool smuggling in $C_x$.

Punctilious handover (narrow bridges)

Strict role blindness means oqtest cannot read $L_x$, yet harness generation may need typed signatures from $C_x$. Handover artifacts are verify-enforced bridges (not shadow RS/DS documents) with explicit producer and consumer roles. Use them only when normal atomic joins cannot express the need; keep payloads minimal (signatures, enums, fixtures).

Hand-in-glove pairing with High Assurance

The assurance profile is source of truth for trace rules. Ysbuild includes the module architecture primer and profile YAML in cached general_introduction so every agent shares one grammar. When the profile changes, ysbuild reloads scopes; verify enforces the same rules on commit.

Optional, not required

Teams can author atomic files by hand, with other IDEs, or via import from brownfield RS/FS/DS. ValidKeep verify is the common gate.

CR-101 vignette

For neonatal dose rules in CR-101: rx adds stakeholder rule fragments; cx updates capability signatures; lx designs algorithm changes; oqtest authors calc-neonatal.oqtest.md; code implements. Each turn is narrow; npx validkeep verify integrates the whole graph on push.

Where to go next

• Impartial audit
• Assurance profiles
• Ecosystem map
• Module architecture hub
• Fractal module model
• Yttrigen Studio