bootstrap

You are bootstrapping the uBPF repository into a clean, auditable semantic baseline. Work from repository evidence first, then reconcile against RFC 9669 and any newer ISA RFCs the user provides. Treat the existing docs/specs/*.md files as canonical artifact targets if they already exist. Update them in place instead of creating parallel copies.

Critical Constraints - Read Before Doing Anything

• Execute phases one at a time, in order.
• In Phase 1 you MUST NOT draft requirements, design, validation, or audit text.
• In Phase 2 you MUST NOT change implementation or tests. Produce only spec artifacts.
• In Phase 3 you MUST focus on low-confidence items, ambiguities, and missing intent. Do not skip directly to approval.
• In Phase 4 you MUST audit the specification set and ISA reconciliation artifacts before treating the baseline as usable.
• In Phase 5 you MUST present the baseline package and wait for user approval before calling the work complete.
• If you find yourself producing code patches, test code, or final approval language before the current phase allows it, STOP and return to the current phase.
• Why this pipeline exists: uBPF already contains extracted specs and ISA reconciliation documents. A monolithic rewrite or code-first shortcut will reintroduce drift between the codebase, the specs, and RFC-facing compatibility notes.

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

• Canonical spec set:
  • docs/specs/requirements.md
  • docs/specs/design.md
  • docs/specs/validation.md
  • docs/specs/audit-report.md
  • docs/specs/isa-reconciliation.md
• Primary implementation roots:
  • vm/
  • ubpf/
  • tests/
  • test_framework/
  • custom_tests/
  • libfuzzer/
  • external/bpf_conformance/
• Supporting context:
  • README.md
  • docs/Contributing.md
  • docs/VerifiedPrograms.md
  • workflows/*.md for prior-art prompts and expected lifecycle shape
• Current long-term goal:
  • Keep uBPF auditable against RFC 9669 and future eBPF ISA RFCs.
  • Enable deterministic LLM-guided extension work for new target ISAs and new eBPF ISA features.

Inputs

Expect the user to provide some combination of:

• A repository root, if different from the current working tree
• Optional focus areas
• Optional new RFC text, links, or notes
• Known problem areas, intentional divergences, or future ISA goals

If the user does not specify artifact paths, default to the existing docs/specs/*.md files listed above.

Required Outputs

Produce these artifacts unless the user explicitly narrows scope:

1. Updated docs/specs/requirements.md
2. Updated docs/specs/design.md
3. Updated docs/specs/validation.md
4. Updated docs/specs/audit-report.md
5. Updated docs/specs/isa-reconciliation.md when ISA/RFC alignment is in scope
6. A coverage statement naming what was examined, excluded, and still unknown

Workflow

Phase 1 - Repository Scan

Build a bounded understanding of the repository before writing anything.

1. Enumerate structure and major subsystems.
2. Read repository docs and existing spec artifacts.
3. Read key API and implementation surfaces, especially:
   • vm/inc/ubpf.h
   • vm/ubpf_vm.c
   • vm/ubpf_loader.c
   • vm/ubpf_instruction_valid.c
   • vm/ubpf_jit*.c
4. Inspect test architecture across tests/, test_framework/, custom_tests/, libfuzzer/, and external/bpf_conformance/.
5. If RFC alignment is in scope, inspect docs/specs/isa-reconciliation.md and any provided RFC material before synthesizing conclusions.
6. Produce a repository analysis summary with architecture, artifact status, gaps, unknowns, and proposed extraction scope.

Critical Rule

Do NOT proceed to Phase 2 until the user confirms the proposed bootstrap scope. Present the repository analysis summary, ask for confirmation or correction, and WAIT.

Phase 2 - Draft or Refresh the Baseline

Refresh the spec artifacts from evidence.

1. Extract or update requirements from observable behavior.
2. Refresh design sections so they explain how the code realizes those requirements.
3. Refresh validation coverage using the real test inventory.
4. If RFC alignment is in scope, reconcile ISA behavior against RFC 9669 and any newer RFC material, classifying universal, divergent, and extension behavior explicitly.
5. Mark every substantive item with confidence and evidence.
6. Preserve stable IDs and existing document structure where possible. Make surgical updates instead of rewriting for style.

Critical Rule

Do NOT proceed to Phase 3 until the draft artifact set exists. The only permitted output of this phase is updated spec and reconciliation text, not code changes or implementation plans.

Phase 3 - Clarification Loop

Drive down ambiguity before auditing.

1. Walk low-confidence and medium-confidence items first.
2. Surface places where implementation behavior may be incidental rather than contractual.
3. Ask whether observed divergences from RFC 9669 or newer RFCs are intentional, transitional, or defects.
4. Record unresolved items as explicit open questions in the spec package rather than silently choosing an interpretation.

Critical Rule

Do NOT proceed to Phase 4 until the user says the baseline is ready for audit. Present unresolved items, ask for confirmation, and WAIT.

Phase 4 - Consistency and RFC Audit

Adversarially verify the baseline.

1. Trace requirements to design and validation.
2. Check backward traceability for undocumented design or tests.
3. Verify terminology, assumptions, constraints, and ID usage are consistent.
4. Re-check RFC reconciliation claims against the cited code and documents.
5. Classify each finding explicitly and explain why it is not a false positive.
6. Update docs/specs/audit-report.md with evidence, severity, impact, and remediation.

Critical Rule

Do NOT proceed to Phase 5 until the audit report and any required spec corrections are complete. If the audit fails, return to Phase 2 or 3 instead of summarizing prematurely.

Phase 5 - Baseline Approval Package

Present the final bootstrap package:

1. Requirements, design, validation, and audit artifacts
2. ISA reconciliation artifact when applicable
3. Coverage statement
4. Remaining open questions and explicitly deferred items
5. Recommended next workflow:
   • Use /evolve for change-driven specification and implementation work
   • Use /maintain for periodic drift audits

Critical Rule

Do NOT declare the repository fully bootstrapped if unresolved high-severity drift findings remain open. State the blockers plainly.

Non-Goals

• Do not invent behavior not evidenced by code, tests, or provided RFCs.
• Do not treat existing workflow prompts as authoritative if they conflict with the repository or spec artifacts.
• Do not mix bootstrap with implementation work unless the user explicitly changes scope.