supergoal

# Supergoal Supergoal turns rough engineering intent into a durable `GOAL_RUN/` package: root spec, root verification, a reviewed dependency graph, sub-goal contracts, evidence, usage, budget controls, and final reporting. ## Core Rule Codex is the planner. Scripts are guardrails. Use files under `GOAL_RUN/` as the project-level source of truth, and use one active Codex `/goal` at a time, normally a selected sub-goal. Do not rely on simultaneous nested goals. Do not treat `init_goal_run.py` or any script as the intelligent decomposition engine. Use scripts only to create an empty scaffold, validate files, select ready work, record usage/evidence, check budget, and maintain state. ## Hard Execution Gate Root files are planning and verification artifacts, not execution goals. Never call `/goal`, `create_goal`, or any goal-starting tool for the whole root objective. Before selecting a sub-goal, confirm pre-launch prerequisites: - `GOAL_RUN/` exists and is filled from repo context and user intent; - `GOAL_RUN/scripts/preflight_goal_run.py GOAL_RUN` has no blockers; - `STATE/CONTROL.json` and `STATE/CONTROL.md` allow execution; - budget hard limits and approval gates do not require stopping. After pre-launch prerequisites pass, run `GOAL_RUN/scripts/select_next_subgoal.py GOAL_RUN`. Goal-starting tools may be used only after it returns a specific ready `SG-XXX`, and the goal command must execute exactly `GOAL_RUN/SUBGOALS/SG-XXX.md`. If the environment cannot actually launch a selected sub-goal `/goal`, stop after printing the exact command and wait. Continue manually only if the user explicitly approves a manual fallback. Do not implement project code beyond inspection, scaffolding, and planning until the package validates and a concrete sub-goal is selected. ## Interruption Recovery Gate When the user interrupts, changes direction, adds or removes scope, or gives new steering while an orchestrated run may be in progress, do not continue normal execution immediately. First perform an interruption recovery check: 1. Identify whether a selected or active sub-goal `/goal` exists from conversation context, `STATE/PROGRESS.json`, `GOAL_COMMANDS.md`, and the user's UI state when needed. 2. Compare the new instruction against the active sub-goal contract in `SUBGOALS/SG-XXX.md`. 3. Classify the impact as `no_active_goal`, `non_affecting`, `affecting_active_goal`, or `uncertain`. 4. Record the user instruction, classification, and decision in `STATE/CONTROL.md` and `STATE/DECISIONS.md`. 5. If `no_active_goal`, apply the change to the plan/control surface, rerun validation or graph review when needed, then continue through normal selection. 6. If `non_affecting`, record whether the change applies after the current goal, to future sub-goals, or to root verification. Tell the user they may continue the current active `/goal`, and do not rewrite its contract. 7. If `affecting_active_goal`, tell the user the active `/goal` contract is stale and ask them to stop/delete it in the UI. Do not proceed until the user confirms it has stopped. Then mark the old sub-goal blocked, superseded, or needs replanning; update contracts, graph, control files, and validation before launching a replacement selected sub-goal. 8. If `uncertain`, ask the user to pause/stop the active `/goal` or answer a targeted clarification before continuing. Do not launch another sub-goal while uncertain. Codex cannot reliably suspend a running `/goal` from outside. It can stop launching the next sub-goal, record the interruption, and ask the user to stop/delete an active goal when the current contract may be invalid. ## Intake And Clarification Gate Do not silently convert a vague rough idea into a fixed plan. Before writing the final `ROOT_SPEC.md`, Codex must perform an intake pass: 1. Inspect the repo and infer all answerable details from files, tests, package metadata, docs, and existing project instructions. 2. Ask enough targeted questions to avoid solving the wrong problem. Do not ask for facts that the repo clearly proves, but do not over-optimize for asking fewer questions. 3. Classify open items as `confirmed_by_repo`, `confirmed_by_user`, `pending_user_confirmation`, `safe_default`, or `blocker`. 4. Ask the user to confirm every `pending_user_confirmation` and answer every `blocker` whose answer materially affects outcome, scope, verification, risk, budget, data, dependencies, approval gates, or user-facing behavior. 5. Do not treat assumptions as permission to execute. A material assumption may be recorded, but Codex must not decompose or execute based on it until it is confirmed by the user, confirmed by repo evidence, or explicitly accepted as a safe default. 6. If material questions exist, ask the user before finalizing `ROOT_SPEC.md`, `ROOT_VERIFICATION`, `GOAL_GRAPH`, or sub-goals. 7. If no material questions exist, record `No blocking clarification needed.` in `GOAL_RUN/INTERVIEW_NOTES.md`. 8. Record every user answer, inferred answer, unresolved question, explicit assumption, and assumption classification in `GOAL_RUN/INTERVIEW_NOTES.md`. 9. For Level 2+ orchestrated runs, explicitly ask for budget limits or present defaults during intake before decomposition. Ask budget as two separate decisions: usage budget and time budget. Usage budget may be specified either as reported tokens (`none`, `soft limit`, `hard limit`, or `unknown`) or as Codex account quota (`weekly quota percent to spend`, `weekly minimum percent left`, and optionally `5h minimum percent left`) when the quota reader is available. 10. Only if the user confirms, declines to set limits, says they do not know, or asks Codex to proceed with defaults may Codex record the default policy: no hard token limit, no hard time limit, max repair sub-goals = 10, and unknown usage is recorded as `unknown`, never estimated or treated as zero. 11. Do not decompose into sub-goals until `INTERVIEW_NOTES.md` contains confirmed answers or approved safe defaults for material assumptions, and the budget policy for Level 2+ runs. No intake record, no final `ROOT_SPEC.md`. No `ROOT_SPEC.md`, no `ROOT_VERIFICATION`. No `ROOT_VERIFICATION`, no DAG. ### Mandatory Budget Intake Gate For Level 2+ For every Level 2+ run, budget intake is a separate hard gate before final `ROOT_SPEC.md` and decomposition. Ask or present defaults as separate user-visible items: 1. Usage budget: ask whether the user prefers reported-token budget, account-quota budget when available, or no hard usage budget. 2. Time budget: ask separately whether the user wants no time limit, a soft time limit, a hard time limit, or unknown. 3. Repair budget: state `max_repair_subgoals = 10` as the default unless the user changes it. Do not merge usage budget, time budget, and repair budget into one question such as `Approve default budget policy?` or `Any budget limits?`. Even when proposing defaults, list usage budget and time budget separately and require confirmation. Adapt the budget questions to the user's language and task context; do not copy this template verbatim. Required decisions to cover: ```text Usage budget: - If account quota was read successfully, say the current quota is readable and offer account-quota budgeting. - If account quota was unavailable or declined, do not present it as an active option; offer reported-token budgeting or no hard usage budget. - If account quota has not been checked yet, try the direct quota check when possible before asking, or tell the user it is unchecked and ask whether to try it or use reported tokens/no hard usage budget. Time budget: - Ask whether the run should have no time limit, a soft time limit, a hard time limit, or unknown. Repair budget: - State that the default max repair sub-goals is 10, and ask whether to keep or change it. ``` ## Mandatory Dashboard Viewer Intake Gate For Level 2+ For every Level 2+ run, dashboard viewer intake is a separate hard gate before final `ROOT_SPEC.md` and decomposition. Ask or present the default as a separate user-visible item: 1. Before asking for a preference, explain in one standalone plain-language sentence what the user will see: a read-only progress panel showing sub-goal status, evidence, budget, and overall progress. 2. Ask whether the user wants only the static `GOAL_RUN/REPORTS/dashboard.html` file, or also a local auto-refresh browser viewer after the first successful render. 3. If yes, ask which port to use, with `8765` as the default. 4. If yes, ask whether Codex may request permission for non-sandbox/elevated execution when the environment blocks local port binding. 5. If no, record that the run will use only the static `GOAL_RUN/REPORTS/dashboard.html` file. Do not ask this preference using only terms like `dashboard`, `static HTML`, or `viewer` before the plain-language explanation. It is fine to name the dashboard, but the same sentence must immediately explain what it is and what information the user will see. Do not merge dashboard viewer intake into a generic budget/defaults question. Record the answer in `GOAL_RUN/INTERVIEW_NOTES.md`. Adapt the wording to the user's language and context. A good shape is: ```text Supergoal can show you a dashboard, which is a read-only progress panel with each sub-goal's status, evidence, budget, and overall progress. Do you want me to only update the HTML file, or also start a local auto-refresh browser view? If I start the local view, is the default port 8765 OK? ``` ## Workflow When the user gives a rough engineering idea: 1. Identify the target project root for the user's task, then inspect that target repo enough to understand likely scope, existing tests, package manager, and relevant project instructions. 2. Before intake for long or risky runs, read account quota with the direct `codex_status.py --json` command when possible, then run `scripts/preflight_codex_goal.py` with `--account-quota-status-json` to assess Codex/repo readiness and quota-budget availability. Because quota capture starts Codex CLI/TUI and may need write access to Codex local state under `~/.codex`, request user approval for non-sandbox/elevated execution at the start when the environment requires it. If the user declines, fall back to reported-token/time budget and record quota capture as unavailable by policy. 3. Read or initialize `STATE/CONTROL.json` and `STATE/CONTROL.md`. 4. Run the Intake And Clarification Gate; ask targeted clarification questions when answers materially affect outcome, verification, risk, scope, budget, protected paths, approval gates, dependencies, data, or user-facing behavior. For Level 2+ runs, explicitly ask for usage budget (reported tokens or account quota), time budget, and dashboard viewer preference/port, or present defaults for user approval before decomposition. 5. Record answers, inferred answers, unresolved questions, and assumptions in `GOAL_RUN/INTERVIEW_NOTES.md`. 6. Write `GOAL_RUN/ROOT_SPEC.md` with objective, success definition, non-goals, constraints, assumptions, and verification surface. 7. Write `GOAL_RUN/ROOT_GOAL.md` and `GOAL_RUN/ROOT_VERIFICATION.md/json`. 8. Classify complexity using `references/workflow.md`. 9. Decompose the root objective into verifiable checkpoints, not tiny edits. 10. Write `GOAL_RUN/GOAL_GRAPH.json` and `GOAL_RUN/SUBGOALS/*.md`. 11. Review the graph conservatively; edit only high-confidence duplicate or dependency problems. 12. Run validation/lint scripts and repair the generated package until it passes. 13. Refresh the read-only dashboard after the package first validates. 14. Execute sequential sub-goal `/goal` runs only through the Hard Execution Gate, rereading the control surface before each launch and recording evidence, usage, review, budget, progress, and a refreshed dashboard after each one. 15. Run root verification, refresh the dashboard, and create repair sub-goals if required checks fail. 16. Write `GOAL_RUN/REPORTS/FINAL_REPORT.md` and refresh the dashboard one final time. Choose the smallest mode that satisfies the request: - Level 0: one-shot task; do not create `GOAL_RUN/`. - Level 1: single durable contract. In orchestrated mode, even Level 1 uses `SUBGOALS/SG-001.md` as the executable contract; root files remain planning and verification artifacts. - Level 2: linear milestones; create 3-8 ordered sub-goals. - Level 3: DAG orchestrated goal; create dependency graph with explicit gates. - Level 4: program-level campaign; create a human-in-loop plan and do not imply full autonomy. ## Create The Package For a new orchestrated run, create `GOAL_RUN/` in the target project root, not necessarily the current shell directory. If the user names a subdirectory such as `examples/SWIFT`, the run package belongs at `examples/SWIFT/GOAL_RUN/`. Do not create a root-level `GOAL_RUN/` in the skill repository unless the skill repository itself is the target project. You may use the scaffold script only to copy the standard directory layout, templates, and scripts: ```bash python path/to/skill/supergoal/scripts/init_goal_run.py \ --project-path path/to/target/project \ --run-dir GOAL_RUN \ --title "Short root goal title" ``` After scaffolding, Codex must fill the package from repo context and user intent. Do not leave generic scaffold text as the final plan. Expected package: ```text GOAL_RUN/ README.md INTERVIEW_NOTES.md ROOT_SPEC.md ROOT_GOAL.md ROOT_VERIFICATION.md ROOT_VERIFICATION.json ORCHESTRATION.md GOAL_GRAPH.json GOAL_COMMANDS.md SUBGOAL_GRAPH_REVIEW.md SUBGOALS/ STATE/ PROGRESS.json CONTROL.json CONTROL.md BUDGET.json USAGE_LEDGER.md EVIDENCE.md DECISIONS.md BLOCKERS.md ATTEMPTS.md RISK_REGISTER.md scripts/ REPORTS/ FINAL_REPORT.md ``` ## Decompose Split by verifiable checkpoint, not tiny edits. Prefer discovery and tests before risky implementation. Every sub-goal must include objective, dependencies, allowed scope, out-of-scope items, `done_when`, verification, failure policy, budget policy, anti-gaming rules, evidence requirements, and review gate. Use `references/mode_runbooks.md`, `references/output_contracts.md`, `references/interview_policy.md`, `references/goal_fitness.md`, `references/decomposition_heuristics.md`, `references/subgoal_contract_schema.md`, and `references/anti_gaming_rules.md`. Use `references/human_control_surface.md` whenever the user may need to steer, pause, constrain, or reprioritize a long-running run. ## Review The Graph Review the graph before execution. Detect duplicate or redundant sub-goals, dependency direction errors, missing prerequisite edges, over-broad sub-goals, over-small sub-goals, and sub-goals that merely duplicate root verification. Only edit the graph for high-confidence fixes. Record ambiguous concerns as watch items in `SUBGOAL_GRAPH_REVIEW.md` and decisions in `STATE/DECISIONS.md`. Use `references/graph_review_policy.md`. ## Validate Run validation after drafting or editing the package: ```bash python path/to/skill/supergoal/scripts/codex_status.py --json --timeout 45 -C . > /tmp/supergoal_codex_status.json python path/to/skill/supergoal/scripts/preflight_codex_goal.py --project-path . --account-quota-status-json /tmp/supergoal_codex_status.json python GOAL_RUN/scripts/preflight_goal_run.py GOAL_RUN python GOAL_RUN/scripts/validate_goal_graph.py GOAL_RUN python GOAL_RUN/scripts/review_goal_graph.py GOAL_RUN --check-only python GOAL_RUN/scripts/lint_subgoals.py GOAL_RUN python GOAL_RUN/scripts/check_evidence.py GOAL_RUN python GOAL_RUN/scripts/check_budget.py GOAL_RUN ``` Use `codex_status.py --json` as the preferred account-quota readiness check. Run it as a direct shell command before intake, requesting user approval or elevated execution if required by the environment. Then reuse its JSON with `preflight_codex_goal.py --account-quota-status-json`. This avoids less stable nested Codex TUI calls inside preflight. Only use `preflight_codex_goal.py --account-quota-quick-check` when direct JSON capture is not practical. Use `preflight_codex_goal.py` as the Codex/repo readiness check. It can inspect repo state, package hints, and the captured 5h/weekly account quota status. `/goal` availability is reported separately under `manual_confirmations`. Only fall back to reported-token/time budget if direct quota capture fails or the user declines quota-budget setup. Use `preflight_goal_run.py` as the GOAL_RUN package readiness gate before launching a sub-goal. It aggregates structure, graph, contract, evidence, budget, root verification, and human-control checks. It does not decide whether the plan is semantically good; Codex must still review the root spec, graph, and sub-goals. If validation fails, fix the package. Do not weaken verification to make scripts pass. ## Quota Path Semantics Do not ask the user to record the skill install path. Before `GOAL_RUN/` exists, resolve scripts from the loaded Supergoal skill directory, meaning the directory that contains this `SKILL.md`. After `GOAL_RUN/` exists, prefer the copied self-contained tools under `<target-project-root>/GOAL_RUN/scripts/`. Keep these paths distinct: - `<skill-dir>`: loaded Supergoal skill directory; use only before the run package exists or when package scripts are missing. - `<target-project-root>`: project root for the user's task; `GOAL_RUN/` normally lives here. - `<trusted-codex-cwd>`: a stable directory for `codex_status.py -C`; prefer the current workspace root, the target project root if already trusted by Codex, or a trusted parent workspace root. Account quota is account-level, so this directory does not have to be the exact target project, but it must not trigger a `Do you trust the contents of this directory?` prompt. - `<run-dir>`: the generated run package, normally `<target-project-root>/GOAL_RUN`; use this for writing ledgers and state. For quota capture, the `codex_status.py` script path may be `<skill-dir>/scripts/codex_status.py` or `<run-dir>/scripts/codex_status.py`, but `-C` must be `<trusted-codex-cwd>`, never the skill directory and never `GOAL_RUN/`. If `codex_status.py --raw` shows a trust prompt, do not record account quota as unavailable; use an already trusted workspace root for `-C` or ask the user to trust the target directory first. If Codex CLI reports readonly local state such as `attempt to write a readonly database` under `~/.codex/sqlite` or asks to repair Codex local data during quota capture, treat it as sandbox/permission blockage, not as damaged account quota state. Do not run the repair prompt from the skill flow. Request permission to rerun the same direct capture command outside the sandbox/elevated; if the user declines, record quota capture as unavailable and continue with reported-token/time budget options. Preferred quota capture and ledger write after `GOAL_RUN/` exists: ```bash python3 <target-project-root>/GOAL_RUN/scripts/codex_status.py \ --json \ --timeout 45 \ -C <trusted-codex-cwd> \ > /tmp/supergoal_quota_SG-XXX_before.json python3 <target-project-root>/GOAL_RUN/scripts/record_account_quota.py \ <target-project-root>/GOAL_RUN \ --goal SG-XXX \ --phase before \ --status-json /tmp/supergoal_quota_SG-XXX_before.json \ --allow-unavailable ``` ## Dashboard Refresh a read-only HTML dashboard at the main checkpoints of every orchestrated run: ```bash python GOAL_RUN/scripts/render_dashboard.py GOAL_RUN ``` By default, Codex should run this after the package first validates, after each accepted sub-goal, after blocker or repair-subgoal creation, before and after root verification, and after the final report. The dashboard reads `GOAL_RUN/` and writes `GOAL_RUN/REPORTS/dashboard.html`. It is only a status renderer. It must not replace graph review, sub-goal review, evidence recording, budget checks, or Codex semantic judgment. After the first successful render, Codex may start a visible local viewer for the current session: ```bash python GOAL_RUN/scripts/serve_dashboard.py GOAL_RUN --host 127.0.0.1 --port 8765 --refresh 5 ``` Start the viewer only if the user approved it during intake or later explicitly asks for it. This viewer serves `GOAL_RUN/REPORTS/dashboard.html` on `http://127.0.0.1:8765/` with browser auto-refresh. It is optional, read-only, and non-daemonized: keep it running only as a visible terminal/session process, stop it with Ctrl-C when no longer needed, and never treat it as part of orchestration state. If the viewer is not running, continue refreshing the static HTML file normally. ## Execute Sequential Goals Use Sequential Subgoal Goal Mode by default: 0. Confirm pre-launch prerequisites: `GOAL_RUN/` exists, the package is filled, `preflight_goal_run.py` has no blockers, and control/budget allow execution. 1. Run `python GOAL_RUN/scripts/select_next_subgoal.py GOAL_RUN`. 2. Confirm the Hard Execution Gate is now fully satisfied. No selected `SG-XXX`, no `/goal`. 3. Re-read `STATE/CONTROL.json` and `STATE/CONTROL.md`; stop if pause or approval gates apply. 4. If account-quota budget is enabled and no quota baseline exists, capture quota using the Quota Path Semantics above: direct `<target-project-root>/GOAL_RUN/scripts/codex_status.py --json --timeout 45 -C <trusted-codex-cwd>`, then record it with `<target-project-root>/GOAL_RUN/scripts/record_account_quota.py <target-project-root>/GOAL_RUN --status-json <captured.json>` before launching the first sub-goal. Use `record_account_quota.py` internal capture only as fallback. 5. Launch or display the selected sub-goal's exact `/goal` command. Never launch a root-level `/goal`. 6. Execute only that sub-goal's contract. 7. Run local verification. 8. Append evidence to `STATE/EVIDENCE.md`.