evolve

You are evolving uBPF through a spec-first change workflow. Start from the current semantic baseline in docs/specs/, then propagate approved changes through specs, implementation, tests, and RFC-facing reconciliation artifacts.

Critical Constraints - Read Before Doing Anything

• Execute phases one at a time, in order.
• In Phase 1 you MUST NOT change code or spec files. Discover and challenge the request first.
• In Phase 2 you MUST update requirements, design, validation, and reconciliation artifacts before implementation.
• In Phase 3 you MUST audit the proposed spec changes before touching code.
• In Phase 4 you MUST obtain user approval of the spec change set before implementation.
• In Phase 5 you MAY change code and tests, but only to realize approved specification changes.
• In Phase 6 you MUST audit implementation and verification changes before closing the loop.
• If the change touches ISA behavior or target backends, you MUST update docs/specs/isa-reconciliation.md and any affected docs/specs/jit-*.md artifact as part of the spec phase, not as an afterthought.
• If you find yourself writing code before the spec gate passes, STOP and return to the current phase.
• Why this pipeline exists: uBPF needs deterministic extension work for new ISA features and new target ISAs. Code-first changes without spec propagation make future RFC audits and backend evolution unreliable.

Current Pass Tracking

At the start of the workflow and after every phase transition, announce:

CURRENT PHASE: Phase N - <name>
STATUS: In progress
NEXT: Phase N+1 - <name> (blocked until current gate passes)

Repository Context

• Baseline artifacts:
  • docs/specs/requirements.md
  • docs/specs/design.md
  • docs/specs/validation.md
  • docs/specs/audit-report.md
  • docs/specs/isa-reconciliation.md
• Specialized specs may also exist under docs/specs/, including JIT-specific design documents such as jit-*.md.
• Likely implementation roots:
  • vm/ for VM, JIT, loader, and validator changes
  • ubpf/ for assembler/disassembler changes
  • tests/, test_framework/, custom_tests/, and libfuzzer/ for verification

Inputs

Expect the user to provide:

• The desired change
• Optional affected RFC sections, new RFCs, or target ISA notes
• Optional focus files or subsystems
• Optional constraints such as portability, compatibility, or rollout boundaries

If the request is vague, ask for concrete acceptance criteria, measurable bounds, and compatibility expectations before proceeding.

Required Outputs

Produce a traceable change package containing:

1. A requirements patch or requirements update
2. A specification patch covering design, validation, and reconciliation artifacts
3. Implementation and test changes
4. At least one spec audit result
5. At least one implementation audit result
6. A summary of what changed, what did not change, and any deferred follow-up

Workflow

Phase 1 - Requirements Discovery

Clarify the requested change before editing anything.

1. Restate the requested change.
2. Identify affected requirements, new requirements, retired requirements, and impacted invariants.
3. Challenge hidden assumptions, especially around portability, interpreter/JIT parity, verifier assumptions, and RFC compatibility.
4. If the request affects ISA semantics, identify whether the change is:
   • Implementation catch-up to current RFC behavior
   • An intentional extension
   • Preparation for a future RFC
   • A new target ISA/backend capability
5. Produce a scoped requirements change summary.

Critical Rule

Do NOT proceed to Phase 2 until the user explicitly says discovery is complete. Present the scoped requirements change summary, ask for confirmation, and WAIT.

Phase 2 - Specification Changes

Propagate the approved requirements intent downstream.

1. Update the affected requirements.
2. Update design sections explaining the realization strategy.
3. Update validation coverage and any traceability matrices.
4. Update docs/specs/isa-reconciliation.md when the change affects RFC-facing behavior.
5. Update any affected specialized spec artifacts under docs/specs/.
6. Check completeness, conflicts, and unchanged invariants.

Critical Rule

Do NOT proceed to Phase 3 until the specification change set is complete. The only permitted outputs of this phase are spec artifacts and traceability updates, not code.

Phase 3 - Specification Audit

Adversarially verify the spec package.

1. Reconstruct the user intent.
2. Trace requirements forward into design and validation.
3. Trace design and validation backward to requirements.
4. Check that RFC or ISA reconciliation claims are supported by cited evidence.
5. Record findings with explicit evidence and why disproof failed.
6. Produce a verdict: PASS, REVISE, or RESTART.

Critical Rule

Do NOT proceed to Phase 4 unless the spec audit verdict is PASS or the user explicitly accepts the remaining issues. If the verdict is REVISE or RESTART, loop back.

Phase 4 - User Review of Specifications

Present:

1. The requirements change set
2. The specification change set
3. The spec audit findings and verdict
4. A summary of affected and unaffected behavior

Critical Rule

Do NOT proceed to Phase 5 until the user approves the specification changes.

Phase 5 - Implementation and Verification Changes

Realize the approved spec changes.

1. Identify implementation files and tests affected by the approved spec delta.
2. Make the minimum code and test changes needed to realize the new behavior.
3. Keep interpreter, JIT, loader, validator, and test expectations aligned.
4. If the change adds a target ISA or RFC behavior, ensure the runtime artifacts read from the updated specs rather than hardcoding stale assumptions.

Critical Rule

Do NOT proceed to Phase 6 until implementation and verification changes are complete. Do not start deliverable packaging from a partially updated tree.

Phase 6 - Implementation Audit

Audit the realized change.

1. Verify every approved spec change is implemented.
2. Verify no undocumented behavior was introduced.
3. Verify tests cover the changed acceptance criteria.
4. Re-check interpreter/JIT parity and target-specific implications when relevant.
5. Produce a verdict: PASS, REVISE-IMPLEMENTATION, REVISE-SPEC, or RESTART.

Critical Rule

Do NOT close the workflow while unresolved high-severity audit findings remain. Loop back to the correct phase instead.

Phase 7 - Delivery

Produce the final handoff:

1. Updated artifacts and code
2. Audit results
3. Coverage statement
4. Commit/PR summary that traces intent -> specs -> implementation -> verification

Non-Goals

• Do not skip the spec gate just because the implementation looks obvious.
• Do not silently widen scope beyond the approved change request.
• Do not leave RFC-facing reconciliation stale when behavior changes.