mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-26 18:31:34 +01:00
docs(runner): authorize phase 2 and clarify tutorials
This commit is contained in:
1 parent
1222f5fc53
commit
77fce1a6ed
6 files changed
+33
-15
No files matched your search
@@ -1,6 +1,7 @@
|
||||
# Native Runner Tutorials
|
||||
|
||||
The tutorials are cumulative and are always run from the repository root.
|
||||
Each tutorial starts with an explanation of what the phase is and what the phase proves.
|
||||
|
||||
## Accepted implementation phases
|
||||
|
||||
@@ -16,4 +17,5 @@ The tutorials are cumulative and are always run from the repository root.
|
||||
- [Dated shadcn/ui and AI Elements compatibility note](research/2026-08-07-ui-library-compatibility.md)
|
||||
- [Package README](../README.md)
|
||||
|
||||
Phase 2 is authorized and in progress. Add its tutorial when its runnable tracer is ready.
|
||||
Later tutorials are added only after their phase is authorized and implemented.
|
||||
@@ -1,10 +1,14 @@
|
||||
# Native Runner Cumulative End-to-End Tutorial
|
||||
|
||||
This tutorial grows with each accepted phase. At Phase 1, the complete runnable
|
||||
system includes the Phase 0 Rust mock-core tracer plus a language-neutral PRP
|
||||
schema/fixture corpus, deterministic TypeScript reducer, Rust parity oracle, CLI
|
||||
replay, and standalone browser replay. There is intentionally no daemon, network
|
||||
connection, live harness, or Paperclip bridge.
|
||||
## What this tutorial is
|
||||
|
||||
This tutorial combines each accepted Native Runner phase into one procedure. It currently includes Phase 0 and Phase 1.
|
||||
|
||||
## What this tutorial proves
|
||||
|
||||
This tutorial proves that the standalone package boundary and static replay path work together. It does not use a live harness or Paperclip.
|
||||
|
||||
The current system includes the Rust mock-core tracer and the shared protocol fixtures. It also includes CLI replay and browser replay.
|
||||
|
||||
## Current end-to-end path
|
||||
|
||||
|
||||
@@ -1,11 +1,16 @@
|
||||
# Phase 0: Run the Standalone Tracer
|
||||
|
||||
## Outcome
|
||||
## What this phase is
|
||||
|
||||
You will install only the runner workspace's declared Node tools, compile its
|
||||
Rust and TypeScript surfaces, run their tests and static checks, start the Rust
|
||||
in-memory mock core, validate the minimal shared fixture, print a deterministic
|
||||
result, and return to the shell. Paperclip itself does not start.
|
||||
Phase 0 is the smallest standalone runner path. It uses a mock control plane and does not start Paperclip.
|
||||
|
||||
## What this phase proves
|
||||
|
||||
This phase proves that the package has an independent Rust boundary. It also proves that Rust and TypeScript accept the same fixture.
|
||||
|
||||
You will install the package tools. You will compile the Rust and TypeScript code. You will run the tests and checks.
|
||||
|
||||
You will start the Rust mock core. The tracer validates one fixture and prints a deterministic result. The process then stops.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
|
||||
@@ -1,8 +1,14 @@
|
||||
# Phase 1: Validate and Replay a PRP Fixture
|
||||
|
||||
This tutorial exercises the complete Phase 1 tracer bullet from a clean checkout:
|
||||
validate a language-neutral fixture, reduce its events in the CLI, and inspect
|
||||
the same snapshot in the standalone browser page.
|
||||
## What this phase is
|
||||
|
||||
Phase 1 is a static replay path for a Paperclip Runner Protocol fixture. It uses the same reducer in the CLI and browser.
|
||||
|
||||
## What this phase proves
|
||||
|
||||
This phase proves that Rust and TypeScript accept the same protocol data. It also proves that duplicate events do not change the result.
|
||||
|
||||
The tutorial validates one fixture. It reduces the events in the CLI. It then shows the same snapshot in the browser.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ This document is the implementation-phase plan for [`paperclip-native-runner-spi
|
||||
|
||||
All implementation starts inside `packages/paperclip-runner/` with protocol and mock-control-plane layers. These standalone phases do not modify Paperclip control-plane semantics. A real Paperclip bridge is a late, separately reviewed phase after the standalone contract passes conformance tests.
|
||||
|
||||
Only Phase 0 and Phase 1 implementation issues may be created initially. After both phases have runnable demos, tests, package-local documentation, tutorials, journal entries, QA evidence, and human checkpoints, update this plan and the spike specification with what was learned before creating tasks for later phases. Later phase tasks are intentionally deferred.
|
||||
Phase 0 and Phase 1 are complete. Their runnable demos, tests, package-local documentation, tutorials, journal entries, and evidence satisfy the first task-creation gate. The human authorized Phase 2 on August 7, 2026. Create only the Phase 2 implementation issue now. Keep Phase 3 and later issues deferred until the Phase 2 human checkpoint is complete.
|
||||
|
||||
## Non-negotiable delivery rules
|
||||
|
||||
@@ -18,6 +18,7 @@ Only Phase 0 and Phase 1 implementation issues may be created initially. After b
|
||||
6. **Tracer bullet in every phase:** each phase ends with a useful executable path, even if it is intentionally narrow.
|
||||
7. **Evidence in every phase:** record the exact commands run, versions used, results, known gaps, and links to artifacts/screenshots.
|
||||
8. **Documentation in every phase:** add reference documentation plus a hand-run tutorial. Add each tutorial to a Native Runner tutorial index and to a cumulative end-to-end tutorial.
|
||||
Start each tutorial with short sections that explain what the phase is and what its runnable proof establishes. Use Simplified English for these sections and for the procedure.
|
||||
9. **OKF engineering journal:** maintain a Google Open Knowledge Format journal using current OKF v0.2 conventions: Markdown files, YAML frontmatter, typed entries, timestamps, links, and index pages. Add a journal usage guide before implementation begins.
|
||||
10. **Human checkpoint in every phase:** the board/user can run the tutorial and accept or request changes before the next dependent phase starts.
|
||||
11. **Commit by phase:** create small, reviewable commits during each phase. Each phase ends with a named checkpoint commit after QA and human acceptance.
|
||||
|
||||
@@ -6575,7 +6575,7 @@ Never change an active run from native to legacy mid-session.
|
||||
|
||||
The implementation phases, dependency policy, package-local documentation layout, human checkpoints, and retained future backlog now live in [`paperclip-native-runner-implementation-plan.md`](./paperclip-native-runner-implementation-plan.md).
|
||||
|
||||
The spike specification remains the normative contract. Keep it updated when implementation evidence changes architecture, protocol, security, persistence, API, UI, performance, or exit criteria. Keep sequencing and task-creation details in the implementation plan. Only Phase 0 and Phase 1 tasks may be created initially; revise both documents after their human checkpoints before creating later-phase tasks.
|
||||
The spike specification remains the normative contract. Keep it updated when implementation evidence changes architecture, protocol, security, persistence, API, UI, performance, or exit criteria. Keep sequencing and task-creation details in the implementation plan. Phase 0 and Phase 1 are complete. The human authorized the Phase 2 task on August 7, 2026. Keep Phase 3 and later tasks deferred until the Phase 2 human checkpoint is complete.
|
||||
|
||||
## 30. Dependency sequencing
|
||||
|
||||
|
||||
Reference in new issue
Block a user