Implementation Plan: Contract Recovery Nudge — Resume Session to Emit Missing Structured Output Token

[Trecek]

Summary

When a headless run_skill session completes successfully (exit_code=0, cli_subtype=success) but the model omits the mandatory structured output token (e.g. plan_path = /abs/path before %%ORDER_UP%%), the system currently marks it as adjudicated_failure with retry_reason=CONTRACT_RECOVERY and triggers a full retry. This PR introduces a resume nudge — a lightweight fourth recovery tier that resumes the same session with a short feedback prompt asking the model to emit the missing token. On success, the SkillResult is patched to success=True. On failure, the original CONTRACT_RECOVERY result is returned unchanged (zero regression risk).

Architecture Impact

Process Flow Diagram

%%{init: {'flowchart': {'nodeSpacing': 40, 'rankSpacing': 52, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;

    %% TERMINALS %%
    START([run_headless_core entry])
    SUCCESS([SkillResult — success])
    RETRY([SkillResult — needs_retry<br/>CONTRACT_RECOVERY])
    ERROR([SkillResult — failure<br/>other subtype])

    subgraph Invocation ["Phase 1 — Headless Invocation"]
        direction TB
        ResolveModel["_resolve_model<br/>━━━━━━━━━━<br/>override › step › default"]
        BuildCmd["● build_full_headless_cmd<br/>━━━━━━━━━━<br/>prompt transforms:<br/>skill prefix · completion directive<br/>cwd anchor · plugin-dir · add-dirs"]
        RunSubproc["runner subprocess<br/>━━━━━━━━━━<br/>claude --print … --output-format stream-json<br/>timeout = cfg.timeout"]
    end

    subgraph Evaluation ["Phase 2 — Result Evaluation (_build_skill_result)"]
        direction TB
        ParseResult["parse_session_result<br/>━━━━━━━━━━<br/>NDJSON → ClaudeSessionResult<br/>subtype · result · assistant_msgs · tool_uses"]
        ChannelBRec["channel B recovery attempts<br/>━━━━━━━━━━<br/>_recover_from_separate_marker<br/>_recover_block_from_assistant_messages<br/>_synthesize_from_write_artifacts"]
        ContentState{"content state?<br/>━━━━━━━━━━<br/>COMPLETE / ABSENT<br/>CONTRACT_VIOLATION<br/>SESSION_ERROR"}
        BudgetGuard["_apply_budget_guard<br/>━━━━━━━━━━<br/>consecutive retry count<br/>vs max_consecutive_retries"]
        CRGate{"● CONTRACT_RECOVERY gate<br/>━━━━━━━━━━<br/>subtype == adjudicated_failure<br/>AND write_call_count ≥ 1<br/>AND not already needs_retry?"}
    end

    subgraph NudgeAttempt ["Phase 3 — _attempt_contract_nudge (NEW FLOW)"]
        direction TB
        NudgeGate{"● CONTRACT NUDGE gate<br/>━━━━━━━━━━<br/>retry_reason == CONTRACT_RECOVERY<br/>AND needs_retry<br/>AND session_id present?"}
        ExtractHints["● _extract_missing_token_hints<br/>━━━━━━━━━━<br/>scan raw NDJSON stdout<br/>match path-capture patterns<br/>collect last Write/Edit file_path"]
        HintsCheck{"● hints found?<br/>━━━━━━━━━━<br/>at least one (token_name, path)<br/>pair extracted"}
        BuildNudgePrompt["● build nudge prompt<br/>━━━━━━━━━━<br/>'You wrote the file but omitted token.<br/>Emit ONLY: {token} = {path}\n{marker}'"]
        BuildResumeCmd["● build_headless_resume_cmd<br/>━━━━━━━━━━<br/>claude --print {prompt}<br/>--resume {session_id}<br/>--output-format json (60 s timeout)"]
        RunNudge["● runner — nudge subprocess<br/>━━━━━━━━━━<br/>lightweight resume session<br/>timeout = _NUDGE_TIMEOUT (60 s)"]
        ParseNudge["● parse_session_result (nudge)<br/>━━━━━━━━━━<br/>NDJSON → nudge ClaudeSessionResult"]
        PatternsCheck{"● combined patterns satisfied?<br/>━━━━━━━━━━<br/>original result + nudge result<br/>vs expected_output_patterns"}
        MergeTokens["● _merge_token_usage<br/>━━━━━━━━━━<br/>additive merge:<br/>input · output · cache tokens"]
    end

    subgraph Outcome ["Phase 4 — Outcome Resolution"]
        direction TB
        PatchSuccess["patch SkillResult → success<br/>━━━━━━━━━━<br/>success=True · needs_retry=False<br/>result = original + nudge output<br/>merged token_usage"]
        FallThrough["fall-through: keep original<br/>━━━━━━━━━━<br/>CONTRACT_RECOVERY needs_retry=True<br/>caller pipeline triggers full retry"]
        SessionLog["flush_session_log<br/>━━━━━━━━━━<br/>write diagnostics to<br/>~/.local/share/autoskillit/logs/"]
    end

    %% MAIN FLOW %%
    START --> ResolveModel
    ResolveModel --> BuildCmd
    BuildCmd --> RunSubproc
    RunSubproc --> ParseResult

    ParseResult --> ChannelBRec
    ChannelBRec --> ContentState
    ContentState -->|"COMPLETE"| BudgetGuard
    ContentState -->|"ABSENT / SESSION_ERROR"| BudgetGuard
    ContentState -->|"CONTRACT_VIOLATION"| CRGate
    CRGate -->|"yes — promote to CONTRACT_RECOVERY"| BudgetGuard
    CRGate -->|"no write evidence"| BudgetGuard

    BudgetGuard --> NudgeGate

    NudgeGate -->|"yes — attempt nudge"| ExtractHints
    NudgeGate -->|"no — skip"| FallThrough

    ExtractHints --> HintsCheck
    HintsCheck -->|"no hints"| FallThrough
    HintsCheck -->|"hints found"| BuildNudgePrompt
    BuildNudgePrompt --> BuildResumeCmd
    BuildResumeCmd --> RunNudge
    RunNudge -->|"exception / timeout"| FallThrough
    RunNudge -->|"subprocess complete"| ParseNudge
    ParseNudge --> PatternsCheck
    PatternsCheck -->|"patterns not found"| FallThrough
    PatternsCheck -->|"patterns satisfied"| MergeTokens
    MergeTokens --> PatchSuccess

    PatchSuccess --> SessionLog
    FallThrough --> SessionLog

    SessionLog --> SUCCESS
    SessionLog --> RETRY
    SessionLog --> ERROR

    PatchSuccess -.->|"nudge_recovery_success"| SUCCESS
    FallThrough -.->|"original CONTRACT_RECOVERY"| RETRY
    BudgetGuard -.->|"other subtypes"| ERROR

    %% CLASS ASSIGNMENTS %%
    class START,SUCCESS,RETRY,ERROR terminal;
    class ResolveModel,BuildCmd,RunSubproc phase;
    class ParseResult,ChannelBRec handler;
    class ContentState,CRGate,NudgeGate,HintsCheck,PatternsCheck stateNode;
    class BudgetGuard detector;
    class ExtractHints,BuildNudgePrompt,BuildResumeCmd,RunNudge,ParseNudge,MergeTokens newComponent;
    class PatchSuccess,FallThrough,SessionLog output;

Loading

Closes #747

Implementation Plan

Plan file: /home/talon/projects/autoskillit-runs/impl-20260411-223302-876755/.autoskillit/temp/make-plan/contract_recovery_nudge_plan_2026-04-11_223800.md

🤖 Generated with Claude Code via AutoSkillit

[Trecek]

AutoSkillit PR Review — Verdict: changes_requested

[Trecek]

[critical] slop: Duplicate assertion assert param.default == "" appears twice consecutively (L3465 and L3466). The second assertion is a copy-paste error — it can never catch a different failure than the first and provides zero additional coverage. Remove the duplicate line.

[Trecek]

Investigated — this is intentional. L3465 is an assignment param = sig.parameters['completion_marker'] (not an assertion); L3466 is the sole assert param.default == ''. The reviewer misidentified the assignment on L3465 as a duplicate assert. No code change needed.

[Trecek]

[warning] bugs: nudge_result.stdout is consumed without a returncode check. If the subprocess returns a non-zero exit code without raising (e.g., the resume command fails cleanly), parse_session_result receives empty/error output instead of valid NDJSON. If parse_session_result raises on empty input, the exception escapes _attempt_contract_nudge rather than returning None. Add if nudge_result.returncode != 0: return None before this line.

[Trecek]

Investigated — this is intentional. SubprocessRunner is a Protocol whose __call__ returns Awaitable[SubprocessResult] — it never raises on non-zero returncode; the returncode is a field on the returned dataclass. Runner-level failures are already caught by the except Exception block at lines 298–307. parse_session_result is designed to handle non-zero/empty stdout gracefully: it returns EMPTY_OUTPUT for empty stdout and UNPARSEABLE for non-JSON, never producing 'corrupted' output. The subsequent _check_expected_patterns call acts as the gate — if the nudge produced error output, patterns won't match and None is returned. No silent contamination path exists.

[Trecek]

[warning] defense: parse_session_result(stdout) is called without exception handling. If stdout is malformed or empty, a parse error propagates uncaught out of _extract_missing_token_hints and then out of _attempt_contract_nudge — bypassing the graceful None-return contract. Wrap in try/except or validate that stdout is non-empty first.

[Trecek]

Investigated — this is intentional. parse_session_result (session.py) is explicitly documented as falling back gracefully for non-JSON or missing fields. It handles empty/whitespace-only stdout by returning ClaudeSessionResult(subtype=EMPTY_OUTPUT), catches all json.JSONDecodeError exceptions per-line, and always returns a fully constructed ClaudeSessionResult — it has no raise path. No exception handling wrapper needed.

[Trecek]

[info] cohesion: _ndjson_with_write is a module-level helper while TestContractNudge defines similar NDJSON-building helpers as instance methods. Consider making it a @staticmethod on TestContractNudge or a shared fixture for consistency.

[Trecek]

AutoSkillit review found 6 blocking issues. See inline comments.