{"data":{"kind":"file","path":"README.md","version_id":"ljkys4wga85ratszjzrfa3im","entry":{"name":"README.md","path":"README.md","is_directory":false,"size":9661,"modified_at":"2026-09-13T19:12:18.157000","content_hash":"cc8e4cf0f1fa2890a08acf3c07019c865c641431cae4314757b8ac4ee572e033"},"entries":[],"content":"# Branching Decision & Recovery V1\n\nAgentForge-Bench Task 003.\n\nA long-horizon interactive RL environment for decision-making under partial observability, information acquisition, branching, delayed consequences, recovery, and replanning.\n\n## Research Identity\n\nTask 003 is intentionally different from Task 001 and Task 002.\n\n- Task 001 focuses on CUDA kernel optimization, experimentation, and performance-driven decisions.\n- Task 002 focuses on causal debugging and long-horizon data pipeline recovery.\n- Task 003 focuses on decision-making under uncertainty, information acquisition, plausible branching, delayed consequences, temporal credit assignment, recovery, and replanning.\n\nThe benchmark is designed to study whether an agent can gather useful information, form hypotheses, commit to costly decisions, recognize delayed consequences, recover without resetting history, and replan toward a globally verified terminal state.\n\n## Core Loop\n\nPartial Observation\n→ Information Gathering\n→ Hypothesis\n→ Branch Decision\n→ Costly Action\n→ Delayed Consequence\n→ New Observation\n→ Recovery / Replanning\n→ Global Validation\n\n## Primary Capabilities\n\nThe environment evaluates:\n\n- partial observability\n- information acquisition\n- hypothesis formation\n- branch selection\n- strategy selection\n- costly decisions\n- risk-aware planning\n- delayed consequences\n- failure diagnosis\n- recovery without episode reset\n- replanning after new information\n- temporal and causal credit assignment\n- sparse and progress-based reward\n- terminal global validation\n- trajectory-level reporting\n- unseen scenario generalization\n\n## Environment Components\n\nTask 003 contains the following major components:\n\n- state model\n- observation model\n- information acquisition\n- inspection adapter\n- decision graph\n- branch semantics\n- strategy semantics\n- cost and risk model\n- hidden dependencies\n- delayed consequence model\n- failure and cascade model\n- recovery model\n- replanning model\n- reward contract\n- terminal conditions\n- Oracle\n- independent Verifier\n- hidden scenario evaluation\n- anti-cheat boundary\n- anti-memorization boundary\n- trajectory recording\n- AgentReport\n- Gymnasium adapter\n- Prime Verifiers V1 integration\n- standalone package installation\n- clean-room validation support\n- agent calibration support\n\n## Decision Model\n\nThe environment contains multiple plausible decision branches.\n\nThe agent must select a branch and compatible strategy after gathering sufficient information.\n\nBranches and strategies have different:\n\n- costs\n- risks\n- information requirements\n- downstream consequences\n- recovery behavior\n\nA locally successful action is not necessarily globally successful.\n\nSome branches deliberately produce delayed consequences so that an agent must continue interacting with the environment before the true outcome becomes observable.\n\n## Information Acquisition\n\nInformation-gathering actions expose partial observations about the system.\n\nExamples include:\n\n- system inspection\n- component inspection\n- dependency inspection\n- history inspection\n- state probing\n- metrics inspection\n- validation queries\n\nRepeated information requests do not provide unlimited progress or reward.\n\nThe observation boundary does not expose the correct branch, hidden root cause, optimal strategy, oracle trajectory, or reference solution.\n\n## Delayed Consequences\n\nSome costly decisions schedule consequences that become observable only after additional interaction.\n\nThis creates a temporal dependency between:\n\n1. an earlier decision\n2. subsequent execution\n3. a delayed failure\n4. new evidence\n5. recovery\n6. replanning\n7. final validation\n\nThe agent must therefore reason over a state trajectory rather than treating each action independently.\n\n## Recovery and Replanning\n\nRecovery does not reset the episode or erase historical decisions.\n\nWhen a delayed failure is detected, the agent may need to:\n\n- recover the affected system\n- revise its hypothesis\n- replan\n- select a different branch\n- select a compatible strategy\n- execute the revised plan\n- globally validate the final state\n\nSuccessful recovery restores the active causal state while preserving the historical trajectory.\n\n## Reward\n\nReward is progress-oriented.\n\nReward can reflect:\n\n- useful information acquisition\n- hypothesis formation\n- decision progress\n- repair or recovery progress\n- replanning progress\n- successful terminal verification\n\nRepeated inspection, redundant behavior, invalid actions, and ineffective actions are not intended to provide a reliable reward-farming path.\n\nTerminal success is dominated by actual final-state correctness and global validation.\n\n## Agent Report\n\nTask 003 provides an `AgentReport` model for trajectory-level analysis.\n\nThe report records:\n\n- task_id\n- status\n- planning_depth\n- information_queries\n- branch_decisions\n- wrong_decisions\n- delayed_failures\n- recoveries\n- replans\n- redundant_actions\n- invalid_actions\n- total_cost\n- final_reward\n- terminal\n- success\n\nReports can be serialized with `to_dict()`.\n\nThe report is intended for analyzing agent behavior and failure modes, not only pass/fail outcomes.\n\n## Oracle and Verifier\n\nThe Oracle provides a reference mechanism for validating that the environment contains a solvable successful trajectory.\n\nThe Oracle is not exposed as agent-facing truth.\n\nThe Verifier independently evaluates the resulting terminal state.\n\nVerification requires the relevant terminal conditions, including:\n\n- terminal state\n- successful final state\n- valid branch and strategy\n- no unresolved active failure\n- no pending recovery\n- no pending replanning\n- global validation\n- sufficient logical progress\n\nThe verifier does not rely on the agent's reported result.\n\n## Hidden Evaluation\n\nPublic scenarios are stored in:\n\n`data/scenarios.json`\n\nHidden scenarios are separated from the agent-facing package and are generated/evaluated through the evaluator layer.\n\nHidden evaluation varies scenario properties such as:\n\n- scenario family\n- topology\n- dependency structure\n- symptom profile\n- branch costs\n- branch risks\n- strategy costs\n- strategy risks\n- delayed consequence timing\n\nThe hidden scenarios are intended to test behavior on unseen configurations rather than memorization of public examples.\n\n## Public Scenario Families\n\nThe current public scenarios cover:\n\n- dependency\n- configuration\n- cascade\n\nThe scenario generator supports additional variation for hidden evaluation.\n\n## Prime Verifiers V1\n\nTask 003 integrates with Prime Verifiers V1.\n\nThe Prime implementation provides:\n\n- TaskData\n- Task\n- Taskset\n- Taskset configuration\n- Prime State\n- Prime Toolset\n- Prime Environment\n- environment/taskset loading\n\nThe package declares the Prime evaluation configuration in `pyproject.toml`.\n\n## Gymnasium\n\nTask 003 provides a real Gymnasium environment adapter.\n\nThe adapter exposes:\n\n- structured observation space\n- discrete action space\n- reset\n- step\n- deterministic seeded execution\n\nThe native environment remains responsible for the benchmark semantics.\n\n## Installation\n\nInstall the task as a standalone package from this directory:\n\n`environments/rl/branching_decision_recovery_v1`\n\nThe task declares its runtime dependencies in `pyproject.toml`.\n\nThe package is designed to operate without requiring the AgentForge-Bench repository itself as a runtime dependency.\n\n## Testing\n\nRun the complete Task 003 regression suite from the repository root:\n\n`pytest -q environments/rl/branching_decision_recovery_v1`\n\nThe suite covers:\n\n- task structure\n- imports\n- decision graph\n- observation contract\n- Gymnasium validation\n- reward behavior\n- hidden scenarios\n- Oracle behavior\n- Verifier behavior\n- anti-cheat boundaries\n- scenario generation\n- agent reporting\n- final audit behavior\n\n## Difficulty\n\nInitial target difficulty:\n\nHard\n\nThe architecture supports later Hard → Very Hard scaling through meaningful increases in:\n\n- planning depth\n- information dependencies\n- branch ambiguity\n- causal dependencies\n- delayed consequences\n- recovery complexity\n- unseen scenario variation\n\nDifficulty must come from meaningful state dependencies, information dependencies, planning depth, branching, delayed consequences, and recovery.\n\nDo not add arbitrary failures or unnecessary actions merely to increase difficulty.\n\n## Benchmark Status\n\nCurrent status:\n\nRelease Candidate\n\nTask 003 has passed the current regression and final report audit.\n\nThe environment is not considered permanently frozen until release-candidate validation, standalone clean-room validation, Prime validation, and agent calibration are completed.\n\n## Version\n\nCurrent task package version:\n\n`0.1.0`\n\nThe version is kept separate from the benchmark task identity and may be incremented when the release candidate is finalized.\n\n## Task Identity\n\nTask ID:\n\n`branching-decision-recovery-v1`\n\nTask number:\n\n`003`\n\nDomain:\n\nDecision Making / Stateful Systems / Agentic RL / Recovery / Replanning\n\nPrimary research question:\n\nCan an agent make reliable long-horizon decisions under partial observability when information has a cost, branches have different delayed consequences, and successful completion requires recovery and replanning rather than resetting the episode?\n\n## Design Principle\n\nThe benchmark should reward agents for making meaningful progress through the underlying state dependencies.\n\nDifficulty should emerge from reasoning-relevant interactions between:\n\n- information\n- hypotheses\n- decisions\n- costs\n- risks\n- dependencies\n- delayed consequences\n- failures\n- recovery\n- replanning\n- final validation\n\nThe benchmark should not rely on arbitrary action inflation or artificial failure injection.\n","encoding":"utf-8","truncated":false,"total_bytes":9661},"status":null}