Skip to content

fix(work-on): self-heal legacy gates instead of mislabeling needs-human #3053

Description

@rapiercraft-forgedock

Problem

Recovered/in-flight issues with valid legacy FORGE:INVESTIGATOR reports are being mislabeled needs-human after implementation and validation pass, solely because those historical comments predate ACCEPTANCE_CHECK: emission. The same false-human escalation class also covers mechanically resolvable migration-number collisions and builder-contract scope drift.

Observed in a live AlterLab orchestration on 2026-08-05:

  • RapierCraftStudios/AlterLab#32344, #32423, and #32525: valid local commits and quality gates passed, then blocked only for missing legacy ACCEPTANCE_CHECK: lines.
  • RapierCraftStudios/AlterLab#32408: blocked on a migration prefix already used by current staging, although choosing the next valid number is mechanical.
  • RapierCraftStudios/AlterLab#32534: blocked on repairable contract/file-scope drift plus legacy acceptance metadata.

Root Cause

  1. commands/work-on/build.md Phase B6.5 treats an empty acceptance spec as an unrecoverable block and directly adds needs-human.
  2. commands/work-on/investigate.md Phase 1A exits immediately for any completed investigator comment, so the build instruction to “re-run investigate” cannot regenerate or backfill the missing checks.
  3. commands/work-on/build/implement.md Phase I4 maps every migration collision directly to needs-human, without distinguishing a safe filename/version collision from a semantic migration conflict.
  4. commands/work-on/build/implement.md treats a stale/wrong builder contract as human-only instead of returning to contract/architecture repair.

This violates the pipeline rule that needs-human is reserved for genuine human judgment, external authority, procurement, or evidence-based review escalation.

Acceptance Criteria

  • A completed legacy investigator report with no ACCEPTANCE_CHECK: lines is automatically given an append-only acceptance-spec backfill derived from the issue criteria/recommendation; the existing investigation verdict and history remain intact. [type:unit]
  • Build re-fetches and executes the backfilled spec instead of adding needs-human; if no machine-checkable criterion exists, the documented type=skipped sentinel is emitted and review remains the human quality gate. [type:unit]
  • Backfill is idempotent and cannot create duplicate acceptance-spec annotations on repeated resumes. [type:unit]
  • A pure migration filename/version collision is repaired by selecting the next valid migration identifier and re-running collision/order checks; only semantic dependency conflicts may escalate. [type:unit]
  • Builder-contract file/scope drift returns to contract/architecture repair and records the amendment; only genuinely incompatible constraints may escalate. [type:unit]
  • Regression coverage proves all three repairable conditions do not add needs-human, while genuine review/merge/human-authority blockers still do. [type:regression]

Affected Files

  • commands/work-on/investigate.md
  • commands/work-on/build.md
  • commands/work-on/build/implement.md
  • relevant spec/conformance tests

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working. Managed by ForgeDock.priority:P1High priority

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions