Forge Platform

Handbook

Self-Host Gap Assay

Recommendation vocabulary (current state): Manual self-hosting available now · Lenses-visible self-hosting was blocked by M1/M2 gaps until this slice ships · Automated self-hosting (agent loop without human Composer)…

Assay questions

  1. Can a ForgeRun be created from a static sample?
    Yes. samples/forge_run.sample.json and the correlated bundle under sprints/selfhost-alpha/samples/ provide copy/paste and validation targets (scripts/validate_selfhost_chain.py).

  2. Can a ForgeRun represent intent, approval, workcell activity, LCDL/Fleet placeholders, EvidencePacket, and decision state?
    Yes in static JSON. The selfhost sample chain includes ApprovalRequest, AgentRun (local_runner), WorkcellResult, LCDLTraceSummary (skipped placeholder), FleetJobSummary (unknown placeholder), EvidencePacket, decision on the ForgeRun, and follow_on_sparks.json.

  3. Can Lenses currently render or ingest that sample? If not, what was missing?
    Before this change: only React presentational primitives existed; there was no file-backed import of .forge/runs/*.
    After this change: GET /api/project/<slug>/forge-runs lists and loads run bundles from the workspace child repo.

  4. Can a safe local run be represented without Fleet?
    Yes. scripts/selfhost_runner.py dispatches allowlisted actions only; no Fleet job IDs are required for alpha (Fleet remains placeholder evidence).

  5. Can a whitelisted local script produce EvidencePacket output?
    Yes. Runner writes local-runner/result.json; scripts/selfhost_import_evidence.py merges summaries into evidence/evidence_packet.json and updates forge_run.json evidence status.

  6. Can human approval be represented before execution?
    Yes. approvals/<approval_id>.json must be state: approved and the action field must gate the requested action_id.

  7. Can follow-on Sparks be produced from evidence?
    Partially. Static sparks ship in follow_on_sparks.json / evidence_packet.follow_on; importer appends a SPARK-IMPORTED-FROM-RUN entry for automation smoke. Native Studio Spark editor is still out of scope.

  8. What must stay out of scope for alpha?
    Raw shell from Studio, Hermes/Factory/OpenClaw orchestration, full Fleet execution, live LCDL traces, arbitrary auto-patches, chat-only approvals.

Current state

  • Schemas through v1 including LocalRunnerAction/Result.
  • Static chain validates; scripts/check_foundation.py enforces samples + chain.
  • Local runner + importer implemented; run store documented.

Blocking gaps (residual)

  • Policy / RBAC: Lenses forge-run writes (decision transitions) remain minimal; production hardening needs review.
  • CI wiring: Optional follow-up to run check_foundation + validate_selfhost_chain in forge-platform CI explicitly.
  • Fleet parity: Template mapping from LocalRunner actions is documentation-only until R4.

Fastest path

  1. Keep .forge/runs/ seeded from sprints/selfhost-alpha/fixtures/ for demos.
  2. Run python3 scripts/selfhost_runner.py … check_foundation then python3 scripts/selfhost_import_evidence.py.
  3. Open Lenses Studio on the workspace that lists forge-platform as a child → Forge Platform run nav.

Required files (inventory)

Area Path
Schemas schemas/local_runner_action.v1.schema.json, schemas/local_runner_result.v1.schema.json
Samples samples/approval_request.sample.json, samples/local_runner_*.sample.json
Chain sprints/selfhost-alpha/samples/*
Runner scripts/selfhost_runner.py, scripts/selfhost_import_evidence.py, scripts/generate_contract_gap_register.py, scripts/validate_selfhost_chain.py
Docs docs/selfhost-run-store.md, roadmap updates, sprint charge.md
Lenses lenses/platform_selfhost_runs.py, API + Studio route

Suggested next prompt

Run Composer 21-selfhost-alpha-architecture.md (from the bundled pack) for Architecture Versona review of Fleet migration and ID correlation, then 24-m2-lenses-selfhost-control-plane.md for UX copy on decision transitions.

Current state (summary)

Ready for local demos; Hermes not required.

Blocking gaps (summary)

Hardening RBAC writes and CI automation.

Fastest path (summary)

Fixture → runner → importer → Lenses.

Required files (summary)

See table above.

Suggested next prompt (summary)

Composer 21 then 24 as above.