Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[REC-AR5][P0] Deterministic Recovery Action Package and Human Escalation UX

Open
  • Is something wrong?
#374 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
github, python
Domain
ai-infra-agents, backend

Research direction

Read REC-AR0/AR1/AR2 and the coordination issues #126 and #311 first; this issue does not name implementation files or tests. Map the existing Controller authority, approval, credential isolation, and reporting paths, then define scenario coverage for the four listed handoffs, including crash/restart and offline fake effects. Done means independently verifiable, secret-redacted handoffs meet the acceptance criteria without changing default single-agent behavior; do not run paid live evaluations without explicit approval.

Written by the indexing model from the issue text.

Description

Parent: #354 · Stage: MVP M1 · Priority: P0 (promoted from P1) · No Advisor runtime prerequisite.

Goal

Make every supported stop actionable with Controller-verified diagnosis first, without human interpretation of raw block_reason or a paid LLM call. Extend existing status / status --json and safe recovery diagnostics; do not duplicate #260's authoritative symptom-indexed documentation.

Deliverables

  1. A bounded RecoveryActionPackage or equivalent projection keyed by #369 StopReasonCode and authoritative stop outcome, containing verified phase/issue/PR, candidate SHA, unpushed worktree/commit preservation information (when available), pending K9/K10 IDs and exact externally verified target, effect identity/stage, observed vs required conditions, possible operator options and policy restrictions.
  2. For REMOTE BLOCKED, reuse Controller unblock(dry_run=True) read/reconcile logic or extract a shared read-only inspector with identical decisions; never call mutating unblock inside status. Clarify that ordinary cached status is a snapshot, while an explicit live dry-run revalidates GitHub facts, may require credentials and uses the correct lock/ownership rules. Label freshness on every claim. A dry-run's possible next Phase is not an automatic transition or authorization.
  3. For unchanged-phase exceptions, show existing resume instructions and budget/reconciliation caveats; for FAILED, do not suggest unblock; for LOCAL BLOCKED, do not fabricate an unblock edge; for #126 future pause, defer to the interaction owner.
  4. Show exact approved commands and payload references from currently persisted action records, including status --action, unblock --approve-action / --decline-action, --bind-evidence, or a plain unblock only where actually applicable. Never invent a target, ID, approval, missing relationship or command flag.
  5. Plain-language symptoms reference one source-of-truth table owned with #260/#258/#265/#311; preserve #311's FIX preflight/eligibility/candidate when action is pending. No worktree reset, loss of unpushed FIX commits, stale approval reuse, raw secret output or unverified Agent/Advisor assertions.
  6. Provide bounded status --json projection with stable key names, explicitly marking observed_at, snapshot/live and UNKNOWN. Keep existing consumers compatible; no state mutation from renderers.

Acceptance criteria

  • Full scenario table: #280→#23 K10 operator action, K9 approval/decline, authentic vs fixed PR #314/#327 false identity conflict, true ambiguous objects, #291 permission classification, typed timeout/resumable, exhausted review loop and LOCAL blocked.
  • Operator can distinguish what is proven, what action is pending, what action is forbidden, what data/worktree must not be touched and exact next valid step.
  • Fake-GitHub tests ensure read-only projection, live drift detection, byte-safe approval/Action IDs, redaction, provider credentials isolation, scheduler locks and dry-run parity.
  • No Advisor dependency; no unverified narrative marked authoritative; default fixed workflow unchanged.

Dependencies

Hard: #369 classification and #370 authority matrix (or approved narrow equivalent before UX implementation). Coordination only: #260, #258, #265, #311, #126. Blocks #375 deterministic MVP evaluation.

Non-negotiable invariants

  • Controller-only authority for phase/task transitions, typed GitHub effects, candidate/evidence identity, authorization, validation, ReviewCertificate and merge; operator-only K9/K10 semantics unchanged. Existing BLOCKED and FAILED exit rules unchanged, LOCAL never gains an unblock edge by implication.
  • No provider receives GitHub mutation credentials, no prompt/source text is authorization, no untrusted shell commands outside existing sandbox policy. Preserve unpushed FIX candidates, effect journals and original evidence; reconcile UNKNOWN outcomes before retrying.
  • No implementation or paid-model benchmark is authorized by this planning change; default single-agent behavior unchanged. Persisted schema migrations require coordination on #23, using the protocol current at implementation time rather than reserving a number.
  • Native GitHub links remain to be established and read back: prose dependencies are not scheduler-enforceable blocked_by edges.

Review rationale: #354 review report.

Dominant language
Python
Stars
0
Forks
0
Avg merge
5h 46m
Merged PRs (30d)
82

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from iceboundrock/AutoForge

All issues in iceboundrock/AutoForge

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.