head 5a425b8196038d5242d2e4f7b79d1a0761a3c6a2 · queued 2026-03-28 12:37:17 · 0 lane(s)
queued 0s
No lanes were selected for this branch head.
Summary
Branch jericho-plan-doc introduces a single new markdown document (todos/jericho.md) that captures the full extraction plan for turning the reusable CI engine into an independent library called JerichoCI, while leaving pikaci as the Pika-specific frontend layer. The document catalogues what has already been accomplished in prior cleanup work (engine/frontend split, removal of ci/forge-lanes.toml, consolidation of the target catalog), identifies three remaining pain points (forge-shaped seam between pikaci and pika-git, historical naming inside jerichoci, and Apple concurrency recovery rough edges), then lays out a four-phase roadmap—replace ForgeLane with a typed catalog API, tighten the JerichoCI public surface, shrink pikaci into a clear frontend, and finally extract JerichoCI into its own repo—along with suggested invariants and the recommended immediate next move.
Tutorial Steps
Establish the plan document
Intent: Create a dedicated planning artifact that records the current state of the JerichoCI extraction, the remaining architectural problems, and a phased roadmap so the team has a single source of truth for upcoming work.
Affected files: todos/jericho.md
Evidence
@@ -0,0 +1,157 @@
+# JerichoCI Extraction Plan
+
+This is the remaining plan for turning the reusable CI engine into `JerichoCI`
+and leaving `pikaci` as the Pika-specific usage layer.
A new file todos/jericho.md is added at the root of the todos/ directory. This is the only change in the branch—no code is modified. The document serves as the authoritative planning reference for the JerichoCI extraction effort.
Record the current architectural baseline
Intent: Document what is already done so that future readers do not re-litigate settled decisions, and so the plan can be reviewed against the actual crate layout.
Affected files: todos/jericho.md
Evidence
@@ -0,0 +1,157 @@
+- `crates/jerichoci/**` now holds the reusable execution engine
+- `crates/pikaci/**` now holds the Pika CLI and CI catalog
+- `crates/pikaci/src/targets.rs` is the authored source of truth for Pika CI targets
+- `crates/pikaci/src/forge_lanes.rs` is now a derived projection for `pika-git`
+- `ci/forge-lanes.toml` is gone
+- all forge-managed CI lanes now go through `pikaci`
The plan opens with a concise summary of the post-cleanup crate layout:
crates/jerichoci/ — reusable execution engine.
crates/pikaci/ — Pika CLI, target catalog (targets.rs), and derived forge projection (forge_lanes.rs).
ci/forge-lanes.toml — deleted; no longer an independent authored manifest.
This baseline makes it clear that the major architectural cut (engine vs. frontend) already exists, and the remaining work is about naming, API shape, and final repo extraction.
Identify remaining pain points
Intent: Enumerate three concrete problems that must be solved before extraction is mechanical, giving each a clear label so they can be referenced in discussions and issues.
Affected files: todos/jericho.md
Evidence
@@ -0,0 +1,157 @@
+### 1. The `pikaci` -> `pika-git` seam is still forge-shaped
+...
+### 2. `jerichoci` still has historical naming and stringly seams
+...
+### 3. Apple concurrency recovery exposed scheduler rough edges
Three problems are called out:
Forge-shaped seam — pika-git consumes a ForgeLane projection from pikaci. The desired contract is a generic "CI catalog entry" API, not something named after the forge.
Historical naming / stringly seams — The engine crate still contains pikaci-era identifiers, shell-string–driven config, and env-var names that leak Pika-specific packaging.
Apple concurrency recovery — Stale compile work on Apple targets can block later lanes until someone manually intervenes. This is flagged as scheduler follow-up work in pika-git, not a blocker for the catalog refactor.
Phase 1 — Replace ForgeLane with a typed CI catalog API
Intent: Define the first concrete deliverable: a shared type in `pikaci` that `pika-git` consumes instead of the forge-named `ForgeLane` struct, shrinking or eliminating `forge_lanes.rs`.
Affected files: todos/jericho.md
Evidence
@@ -0,0 +1,157 @@
+### Phase 1: Replace `ForgeLane` as the shared boundary
+...
+1. introduce a shared exported type in `pikaci` for a CI-exposed target
+2. move `pika-git` off `ForgeLane` and onto that typed API
+3. keep any forge-only display/transport details inside `pika-git`
+4. reduce `forge_lanes.rs` until it is either trivial or gone
Phase 1 targets the boundary between pikaci and pika-git:
Introduce a new exported type in pikaci representing a CI-exposed target.
Migrate pika-git from ForgeLane to that type.
Push any remaining forge-only display/transport concerns into pika-git itself.
Shrink or remove forge_lanes.rs.
Done-when:pika-git no longer imports a forge-named catalog struct, and the shared contract reads as a "Pika CI catalog" rather than a "forge lane manifest."
Phase 2 — Tighten the JerichoCI surface
Intent: Prepare the engine crate for extraction by auditing and renaming anything that still ties it to Pika-specific naming or stringly-typed runtime config.
Affected files: todos/jericho.md
Evidence
@@ -0,0 +1,157 @@
+### Phase 2: Tighten the `JerichoCI` surface
+...
+1. audit `crates/jerichoci/**` for remaining `pikaci`-era names
+2. rename runtime-visible engine contracts that should belong to `JerichoCI`
+3. isolate helper binaries/contracts that are truly engine-owned vs frontend-owned
+4. replace ad hoc stringly runtime setup with more explicit typed config where it helps
Phase 2 focuses inward on crates/jerichoci/:
Audit for leftover pikaci-era identifiers.
Rename runtime-visible contracts to JerichoCI-native names.
Classify helper binaries as engine-owned or frontend-owned.
Replace string-based runtime setup with typed config where warranted.
Done-when:jerichoci could be copied to another repo without dragging Pika naming along, and its public surface is clearly engine-generic.
Phase 3 — Shrink pikaci into a clear frontend
Intent: Make `pikaci` self-evidently the Pika-specific layer so new contributors immediately understand the ownership boundary.
Affected files: todos/jericho.md
Evidence
@@ -0,0 +1,157 @@
+### Phase 3: Shrink `pikaci` into a clear frontend
+...
+1. keep splitting large frontend files into target catalog, command handlers, and rendering
+2. keep local/manual targets and forge-exposed targets in one coherent catalog model
+3. document the intended ownership boundary in a short stable note
Phase 3 refines pikaci itself:
Continue splitting large files into target catalog, command handlers, and rendering.
Unify local/manual and forge-exposed targets in a single catalog model.
Add a short ownership-boundary note for onboarding.
Done-when: A new contributor looking at pikaci can immediately see it is the Pika-specific layer, with no engine concerns leaking upward.
Phase 4 — Extract JerichoCI into its own repo
Intent: Perform the actual repo split as a mostly-mechanical file-move operation, made possible by the cleanup in Phases 1–3.
Affected files: todos/jericho.md
Evidence
@@ -0,0 +1,157 @@
+### Phase 4: Extract `JerichoCI`
+...
+1. decide the final crate/package/binary naming
+2. move `crates/jerichoci/**` and the engine-owned helpers to a new repo
+3. make `pikaci` depend on the extracted engine
+4. keep `pika-git` depending only on `pikaci` and engine data/types it truly needs
Phase 4 is the actual extraction:
Finalize crate / package / binary naming.
Move crates/jerichoci/ and engine-owned helpers to a new repository.
Point pikaci at the extracted crate as a dependency.
Ensure pika-git depends only on pikaci plus any engine data-types it genuinely needs.
Done-when: The repo split is predominantly file motion and dependency rewiring, with no design changes required.
Define enforcement invariants and the immediate next move
Intent: Give the team concrete invariant labels they can turn into CI checks or code-review rules, and state the recommended order of attack to keep architecture converging.
Affected files: todos/jericho.md
Evidence
@@ -0,0 +1,157 @@
+- `JERICHO-001`: `jerichoci` does not reference Pika repo paths, package names, or target ids
+- `JERICHO-002`: `pika-git` consumes a typed Pika CI catalog API, not a separate authored forge manifest
+- `JERICHO-003`: all Pika CI lanes are defined exactly once in `pikaci` code
+- `JERICHO-004`: stale concurrency-group holders are recoverable without manual DB inspection
+...
+1. replace `ForgeLane` with a smaller typed shared CI entry API
+2. then clean up the remaining `jerichoci` naming and runtime contract surface
Four named invariants are proposed for future enforcement:
ID
Rule
JERICHO-001
jerichoci must not reference Pika repo paths, package names, or target IDs.
JERICHO-002
pika-git consumes a typed CI catalog API, not a separate authored forge manifest.
JERICHO-003
All Pika CI lanes are defined exactly once in pikaci code.
JERICHO-004
Stale concurrency-group holders are recoverable without manual DB inspection.
The recommended immediate next move is: first replace ForgeLane with a typed shared CI entry API (Phase 1), then clean up jerichoci naming and runtime contracts (Phase 2). This ordering keeps the architecture converging rather than shuffling complexity before extraction.