Skip to content

AGENTS.md

Latest commit

 

History

History
154 lines (113 loc) · 7.17 KB

AGENTS.md

File metadata and controls

154 lines (113 loc) · 7.17 KB
Raw

Monorepo Project Map

  • ./examples/governed_run_roundtrip/mix.exs: Governed-run proving example for StackLab
  • ./examples/gepa_platform_roundtrip/mix.exs: Deterministic governed GEPA platform roundtrip proof
  • ./examples/lower_facts_roundtrip/mix.exs: Substrate-facing lower-facts proving example for StackLab
  • ./examples/mezzanine_restart_recovery/mix.exs: Stage-2 restart-recovery proof for the neutral Mezzanine substrate
  • ./examples/multi_node_roundtrip/mix.exs: Multi-node proving example for StackLab
  • ./examples/outer_brain_restart_durability/mix.exs: Stage-1 durable restart-authority proof for OuterBrain
  • ./examples/pressure_failover_drill/mix.exs: Pressure and failover proving example for StackLab
  • ./examples/restart_authority_drill/mix.exs: Restart-authority proving example for StackLab
  • ./examples/semantic_host_roundtrip/mix.exs: Semantic host proving example above the lower seam
  • ./examples/session_lineage_drill/mix.exs: Session-lineage proving example for StackLab
  • ./examples/single_node_roundtrip/mix.exs: Single-node proving example for StackLab
  • ./examples/typed_host_roundtrip/mix.exs: Typed host proving example for AppKit and Citadel.DomainSurface
  • ./mix.exs: Tooling root for the StackLab non-umbrella monorepo
  • ./support/citadel_spine_harness/mix.exs: Harness-only assembly package for Citadel and Jido Integration proofs
  • ./support/ai_run_lineage_scanner/mix.exs: Adaptive AI run lineage scanner receipts
  • ./support/lab_core/mix.exs: Shared harness helpers for the StackLab workspace
  • ./support/memsim_harness/mix.exs: Governed-memory substrate simulation helpers for StackLab
  • ./support/model_inference_scanner/mix.exs: Governed model inference boundary scanner receipts
  • ./support/optimization_fabric_scanner/mix.exs: Governed GEPA optimization fabric scanner receipts

AGENTS.md

Onboarding

Read ONBOARDING.md first for the repo's one-screen ownership, first command, and proof path.

Execution Plane dependency wiring

  • support/citadel_spine_harness consumes :execution_plane from ../../../execution_plane/core/execution_plane.
  • The harness may also consume lane/runtime package homes directly, such as ../../../execution_plane/runtimes/execution_plane_node, ../../../execution_plane/runtimes/execution_plane_process, and ../../../execution_plane/protocols/execution_plane_http.
  • Do not point :execution_plane at the sibling repo root. That root is the non-published Blitz workspace project, not the Hex package.

BEAM distribution prerequisite

support/citadel_spine_harness starts short-name distributed BEAM nodes with :peer for remote Spine proofs. Ensure EPMD is running before mix ci or any multi-node/restart-authority harness command:

epmd -daemon
epmd -names

If EPMD is not reachable, the affected tests can fail while starting the local distributed node with an :econnrefused-style reason. Do not work around that by weakening the harness; start EPMD and rerun the same command.

Blitz concurrency

The root Blitz profile is tuned for high-core local workstations while keeping database-heavy test and Credo work below the point where extra package fanout adds contention. Prefer the checked-in mix.exs defaults. Use explicit Blitz CLI options only for local measurement or temporary diagnosis; do not add environment-variable dependency source or concurrency selection.

Dependency Sources

  • Dependency source selection is handled by build_support/dependency_sources.exs and build_support/dependency_sources.config.exs.
  • Local dependency overrides use .dependency_sources.local.exs.
  • Dependency source selection must not use environment variables.
  • Same-repo support/example harness paths may stay in their local mix.exs files; cross-repo dependencies that need fallback behavior belong in the dependency-source manifest.
  • Weld checks helper drift, dependency-source manifests, clone/publish checks, and publish order for this repo; keep the committed dependency on the released Hex Weld line.

Runtime Env

  • Runtime application code under lib/**, support lib/**, example lib/**, and Mix task modules must not call direct OS env APIs such as System.get_env, System.fetch_env, System.put_env, or System.delete_env.
  • Runtime/deployment env reads belong in config/runtime.exs or a Config.Provider.
  • Mix tasks, examples, and harnesses should accept explicit flags, app config, or caller-supplied env maps instead of reading or mutating process env.

Temporal developer environment

Temporal CLI is implicitly available on this workstation as temporal for local durable-workflow development. Do not make repo code silently depend on that implicit machine state; prefer explicit scripts, documented versions, and README-tracked ergonomics work.

Native Temporal development substrate

When Temporal runtime behavior is required, use the stack substrate in /home/home/p/g/n/mezzanine:

just dev-up
just dev-status
just dev-logs
just temporal-ui

Do not invent raw temporal server start-dev commands for normal work. Do not reset local Temporal state unless the user explicitly approves just temporal-reset-confirm.

gn-ten batch review

Use docs/review/gn_ten_batch_review.md at every gn-ten batch closeout. The batch receipt is the review unit; do not substitute raw logs, private command output, or unredacted traces for a reviewed receipt.

Live Provider Checks

For live provider checks, use ~/scripts/with_bash_secrets <command>. It sources ~/.bash/bash_secrets and execs the command. Do not print secret values. Pipe LINEAR_API_KEY via stdin for Linear examples. GitHub live examples use gh auth or GH_TOKEN/GITHUB_TOKEN from the wrapper. Codex SDK examples use the existing Codex/OpenAI machine auth through the wrapper. Live provider smoke is provider/substrate evidence only. Extravaganza product acceptance remains product-owned; StackLab may only validate it externally by running the public Extravaganza command path.

stack_lab Agent Instructions Draft

Owns

  • Full-graph assembled proofs.
  • Fault injection.
  • Restart drills.
  • Local distributed-development harness.
  • gn-ten workspace manifest and proof matrix.

Does Not Own

  • Production business logic.
  • Runtime service ownership.
  • Product UX.
  • Lower execution implementation.

Allowed Dependencies

  • All ranked repos through explicit path dependencies in harness packages.
  • AITrace for proof evidence.

Forbidden Imports

  • Harness helpers must not become production APIs.
  • Proof support packages must not be consumed by product runtime code.

Verification

  • mix ci
  • mix gn_ten.validate
  • Scenario-specific harness tests.

Escalation

If a proof requires new product/platform behavior, implement that behavior in the owner repo first, then return to StackLab for assembled proof.

Blitz 0.3.0 operational note

Root workspace Blitz uses published Hex ~> 0.3.0 by default; .blitz/ is committed compact impact state after green QC. Source and mix.exs changes cascade through reverse workspace dependencies; docs-only changes should stay owner-local.