Handbook
Intelligence node runtime
Forge Intelligence executes intelligence nodes (capabilities) through typed artifact envelopes — one lmeta unit and one FI-local LCDL contract per capability.
Updated
Architecture
| Layer | Role |
|---|---|
src/forge_intelligence/artifacts/ |
Envelope schema validation, artifact store, I1 payloads |
src/forge_intelligence/orchestration/node_executor.py |
Thin adapter: lmeta unit + FI contract; substrate via forge-lcdl only |
lmeta/units/ |
Declarative steps: validate_inputs, emit_envelope, fan_in, budget_guard |
lcdl/contracts/ |
FI-local I/O contracts (intelligence_*_v1) |
registries/capability_maturity.yaml |
Per-capability technical + autonomy axes (schema 1.1) |
registries/intelligence_maturity.yaml |
Intelligence + arena rollups (generated) |
registries/implemented_allowlist.yaml |
Runtime gate — only allowlisted capabilities execute |
Sessions persist envelopes in artifacts.json ({ "items": [ … ] }). Route trace rungs include technical and autonomy from the registry. See DUAL-WIKI.md and VOCABULARY.md.
Maturity model (dual axis)
| Axis | Levels | Meaning |
|---|---|---|
| technical | I0–I4 | Implementation readiness (scaffold → assured) |
| autonomy | A0–A3 | FI decision-autonomy (assisted → monitored) |
Autonomy is not Forge L0–L8 execution autonomy (blueprints-owned). See MATURITY-HIERARCHY.md for capability → intelligence → arena rollups.
- I0_scaffold — unit + contract stub; deterministic envelope emitter
- I1_runtime — on allowlist; envelope/adapter runtime (schema-valid payloads; contract evidence; tests green). Not domain assurance.
- A0_assisted — default; human approves each emit
- A1_supervised — general reasoning + spine; plus Wave I low-risk life intelligences (household-domestic, nutrition, housing-maintenance, mobility, personal-org). High-risk life (mental-health, grief, civic-legal, safety-first-response, etc.) remain A0.
Life A1 tier (Wave I)
| Intelligence | Autonomy | Notes |
|---|---|---|
life.household-domestic-operations |
A1_supervised | Agency/home cases; bounded domestic planning |
life.nutrition-food-access-meal-systems |
A1_supervised | Meal/shopping planning only |
life.housing-maintenance-utilities-repair |
A1_supervised | No unlicensed trade work |
life.mobility-transportation |
A1_supervised | Journey planning; user approves spend |
life.personal-organization-administration |
A1_supervised | Schedule/buffer; not clinical or legal |
| Wellbeing / society crisis intel | A0_assisted | I2 case nodes possible; no autonomy uplift |
Shallow-I1 honesty
Most I1 packs (all life intelligences and general packs except general.reasoning) use a shallow adapter: lmeta units run validate_inputs and emit_envelope with contract-level golden fixtures. Eval suites pass at this level. Do not claim domain-complete reasoning, wired validators, or I2 integration for these packs until validators and semantic fixtures are added per capability.
Nothing left behind: every capability_index.json key has a maturity row (tools/audit_capability_maturity.py).
Validator dispatch
| Path | When |
|---|---|
Domain fn (lcdl/validators/reasoning) |
Wired short names (e.g. lifecycle_exposes_actions) |
Contract runner (validators/contract.py) |
All validator.* bundle IDs — kind-based deterministic checks + envelope schema |
| Skipped | Legacy short names without a wired domain fn |
Index: registries/validator_index.yaml (generated by tools/generate_indexes.py). I2 capabilities must include a validate step in their lmeta unit (audit_capability_maturity.py enforces).
Reference pack: general.reasoning
All 13 reasoning capabilities are I1_runtime / A1_supervised with golden fixtures under packs/general/reasoning/fixtures/ and coordinator flow lmeta/library/general/reasoning/coordinator.lmeta.
Cross-pack handoff
Case graphs (e.g. reskilling T1–T10) chain nodes via the artifact store. Capability aliases (e.g. build_cashflow → build_financial_picture) resolve through registries/capability_aliases.yaml.
Bundle source (curated)
| Topic | Bundle path |
|---|---|
| Pack contract | bundles/human-life-v4.1-audited/core/pack_contract.yaml |
| Cross-intelligence protocol | bundles/human-life-v4.1-audited/core/cross_intelligence_protocol.yaml |
| Artifact envelope schema | bundles/human-life-v4.1-audited/schemas/artifact-envelope.schema.json |
| Reskilling example DAG | bundles/human-life-v4.1-audited/examples/cross_intelligence_reskilling_case.yaml |
Full manifests and evaluation suites remain in the bundle; this handbook links product-facing summaries only.
Verification
./scripts/ci-validate-bundle.sh
pytest -q
python3 tools/audit_capability_maturity.py --fail-on-missing --fail-on-orphan-files
python3 tools/generate_intelligence_maturity.py
python3 tools/generate_node_catalog.py