# PR-8.1 — Disassembler (Roundtrip + Snapshot Reliability)

## Briefing

The disassembler must be:

* Deterministic
* Complete
* Roundtrip-safe (encode → decode → encode)
* Snapshot-friendly

It must fully support:

* New opcodes (MAKE_CLOSURE, CALL_CLOSURE, SPAWN, YIELD, SLEEP)
* Updated syscall representation
* Closure and coroutine instructions

## Target

1. Update disassembler to support all new opcodes.
2. Guarantee stable formatting.
3. Add roundtrip validation tests.

Formatting rules:

* No unstable ordering.
* No implicit formatting differences across platforms.
* Explicit numeric representation where required.

## Acceptance Checklist

* [ ] All opcodes supported.
* [ ] Deterministic formatting.
* [ ] Roundtrip encode/decode test passes.
* [ ] Snapshot tests stable.

## Tests

1. Encode → disasm → reassemble → byte-equal check.
2. Snapshot test for representative programs.
3. Closure/coroutine disasm coverage.

## Junie Instructions

You MAY:

* Modify disassembler module.
* Add snapshot tests.

You MUST NOT:

* Change bytecode encoding format.
* Introduce formatting randomness.

If any opcode semantics unclear, STOP and ask.

---

# PR-8.3 — Layered Test Suite Architecture

## Briefing

Tests must be structured by layer to isolate failures.

Layers:

1. Bytecode encode/decode
2. Verifier
3. VM execution
4. GC behavior
5. Scheduler behavior

## Target

Organize tests into modules per layer.

Enforce:

* No cross-layer assumptions.
* Verifier tests do not execute VM.
* VM tests assume verified input.

Add minimal coverage per layer.

## Acceptance Checklist

* [ ] Tests grouped logically.
* [ ] No duplicated logic.
* [ ] Clear separation of concerns.

## Tests

Add representative tests per layer:

* Encode/decode edge cases.
* Verifier rejects invalid closures.
* VM executes valid programs.
* GC collects unreachable closures.
* Scheduler deterministic ordering.

## Junie Instructions

You MAY:

* Refactor test layout.
* Add missing coverage.

You MUST NOT:

* Merge unrelated layers.
* Hide verifier failures inside runtime traps.

If a test spans layers, STOP and split appropriately.

---

# PR-8.4 — No Legacy Artifacts Enforcement

## Briefing

The codebase must not contain legacy RC/HIP artifacts.

Forbidden patterns:

* retain
* release
* hip
* gate
* borrow
* scope (legacy usage context)
* RC-related modules

## Target

Implement automated check:

* Script or test that scans source tree for forbidden symbols.
* Fails CI if found.

Also:

* Remove dead modules/files.
* Remove unused features.

## Acceptance Checklist

* [ ] Automated legacy scan exists.
* [ ] No legacy symbols present.
* [ ] Dead modules removed.

## Tests

1. Intentionally insert forbidden symbol in test branch → test fails.
2. Scan passes on clean tree.

## Junie Instructions

You MAY:

* Add static scan test.
* Remove dead code.

You MUST NOT:

* Suppress warnings instead of fixing code.
* Leave deprecated modules commented out.

If unsure whether a symbol is legacy or valid, STOP and ask.

---

## Final Definition of Done

* Disassembler roundtrip-safe.
* Deterministic harness in place.
* Layered test suite established.
* No legacy artifacts remain.
* All tests reproducible and stable.

---

# PR-9 — Final Hardening & Baseline Documentation

This phase finalizes the new Prometeu VM baseline after the architectural reset (GC, closures, coroutines, unified syscall ABI, deterministic scheduler).

Goals:

* Consolidated architecture documentation (short, precise, authoritative)
* Minimal and controlled public surface area
* Removal of temporary feature flags
* Final cleanup: dead code, warnings, outdated docs/examples

All PRs below are self-contained and must compile independently.

---

# PR-9.1 — Consolidated Architecture Documentation

## Briefing

The project must include a short, authoritative architecture document in English describing the new baseline.

It must reflect the current state only (no legacy, no transitional wording).

This document becomes the canonical reference for contributors.

## Target

Create `ARCHITECTURE.md` at repository root with sections:

1. Overview

    * Stack-based VM
    * GC-managed heap (mark-sweep, non-compacting)
    * Closures (Model B, hidden arg0)
    * Cooperative coroutines (FRAME_SYNC safepoints)
    * Unified syscall ABI

2. Memory Model

    * Stack vs heap
    * Heap object kinds
    * GC roots (VM + suspended coroutines)

3. Execution Model

    * Interpreter loop
    * Safepoints
    * Scheduler behavior

4. Verification Model

    * Verifier responsibilities
    * Runtime vs verifier guarantees

5. Non-Goals

    * No RC
    * No HIP
    * No preemption
    * No mailbox

The document must be concise (no more than ~4–6 pages equivalent).

## Acceptance Checklist

* [ ] ARCHITECTURE.md exists.
* [ ] No mention of RC/HIP.
* [ ] Reflects actual implementation.
* [ ] Reviewed for consistency with code.

## Tests

Manual review required.

## Junie Instructions

You MAY:

* Create new documentation files.

You MUST NOT:

* Invent features not implemented.
* Reference legacy behavior.

If architecture details are unclear, STOP and request clarification.

---

# PR-9.2 — Public Surface Area Minimization

## Briefing

The public API must be minimal and intentional.

Internal modules must not leak implementation details.

## Target

1. Audit all `pub` items.
2. Reduce visibility to `pub(crate)` where possible.
3. Hide internal modules behind private boundaries.
4. Ensure only intended API is exported.

Focus areas:

* VM core
* Heap internals
* Scheduler internals
* GC internals

## Acceptance Checklist

* [ ] No unnecessary `pub` items.
* [ ] Public API documented.
* [ ] Internal types hidden.
* [ ] `cargo doc` shows clean public surface.

## Tests

* Build documentation.
* Ensure no accidental public modules remain.

## Junie Instructions

You MAY:

* Restrict visibility.
* Refactor module structure.

You MUST NOT:

* Break existing internal usage.
* Expose new APIs casually.

If removing `pub` causes architectural issue, STOP and escalate.

---

# PR-9.3 — Remove Temporary Feature Flags

## Briefing

During refactor phases, temporary feature flags or conditional compilation may have been introduced.

These must not remain in the final baseline.

## Target

1. Identify all feature flags related to transitional behavior.
2. Remove obsolete `cfg` gates.
3. Remove commented legacy branches.
4. Ensure single authoritative execution path.

## Acceptance Checklist

* [ ] No transitional feature flags remain.
* [ ] No commented-out legacy logic.
* [ ] Single execution model.
* [ ] All tests pass.

## Tests

* Full test suite passes without feature toggles.

## Junie Instructions

You MAY:

* Remove obsolete flags.
* Simplify code paths.

You MUST NOT:

* Remove legitimate platform flags.
* Leave partial dead branches.

If unsure whether a flag is temporary or architectural, STOP and ask.

---

# PR-9.4 — Final Cleanup & Quality Sweep

## Briefing

This PR performs the final cleanup pass.

Goal: Zero warnings. No dead code. No outdated examples.

## Target

1. Remove dead modules/files.
2. Remove unused imports and code.
3. Eliminate compiler warnings.
4. Update outdated examples.
5. Remove stale TODOs referencing removed architecture.

Optional (if present):

* Enforce `cargo clippy` clean baseline.
* Ensure `rustfmt` compliance.

## Acceptance Checklist

* [ ] No dead code.
* [ ] Zero compiler warnings.
* [ ] Clippy clean (if configured).
* [ ] Examples reflect new baseline.
* [ ] No TODO referencing RC/HIP.

## Tests

* Full test suite passes.
* Clean build with warnings denied (if configured).

## Junie Instructions

You MAY:

* Remove unused code.
* Refactor minor clarity issues.

You MUST NOT:

* Introduce new features.
* Change runtime semantics.

If cleanup requires semantic change, STOP and split into new PR.

---

## Final Definition of Done

* Architecture documented clearly.
* Public API minimal and controlled.
* No temporary flags remain.
* Codebase clean, warning-free, and aligned with the new VM baseline.