Files
pipelines/internal/author/skill/references/delivery.md
T
alan 95362134aa session export: write only session.html, retire the markdown export
A stage's session was exported twice, as session.md and session.html, and both
files were presented. It is now one html file; the markdown export is retired.

- internal/stage/session_export.go: ExportSession renders and writes exactly one
  file, session.html, via writeSessionFile; renderSessionMarkdown and its helpers
  are gone; SessionExportResult carries HTML/HTMLBytes only. The source read, the
  8 MiB source / 2 MiB rendered bounds, the truncation banner, the
  never-overwrite rule and the honest empty-session handling are unchanged.
- internal/protocol/runs.go: SessionExport drops markdown/markdown_bytes (a
  record written before the change still decodes; unknown fields are ignored),
  and adds LegacySessionMarkdownArtifact with RunStep.PresentedArtifacts(), the
  one Go rule that hides the retired session.md from every artifact listing.
- internal/server/runner.go: evidence.Markdown/MarkdownBytes are no longer copied.
- internal/tui: the artifacts panel, the recorded count and the per-visit summary
  derive from PresentedArtifacts(), so the terminal never lists session.md.
- web/src/app.js: the spike's renderArtifacts applies the same filter.
- android: the Session section is the html export alone in a WebView — SessionView,
  the Markdown/HTML toggle and the session markdown path are removed;
  presentedArtifacts(step) filters the retired session.md out of the per-visit
  gallery, the run gallery and its count, the verdict/selection lists and the
  timeline indicator; data/protocol SessionExport drops the markdown fields.
- Tests pin the single html file, prove no session.md is written and that a
  pre-existing one is neither overwritten nor presented, and prove a legacy
  export record still loads and its session.md is hidden.

The legacy session.md of an older run stays on disk (dated evidence); it is only
no longer produced and no longer presented.

Checks (macOS, Go 1.24, Android Gradle 8.11.1, 18 Oct 2026): gofmt -l . prints
nothing; go build ./... && go vet ./... clean; go test ./internal/... ./cmd/...
-> 19 packages ok, 0 failures; node --check web/src/app.js ok and node --test
web/test -> 20/20; gradle --offline --no-daemon :app:assembleDebug
:app:testDebugUnitTest -> BUILD SUCCESSFUL.

Packaged references checked: internal/author/skill/references/delivery.md and
operations.md both described the session.md+session.html pair, so both are
updated here to describe the single session.html export and the retired, hidden
session.md. README.md and internal/author/skill/SKILL.md carry no session.md
reference and install.go's managed inventory is unchanged (no reference added or
removed). docs/notes/session-html-only.md records the remaining stale shared
documentation (docs/stage-artifacts.md, docs/app-integration-verification.md) for
the docs-fold writer; shared docs are not edited by this item.
2026-10-18 10:06:49 +01:00

82 lines
4.5 KiB
Markdown

# Publish artefacts, name them honestly, keep installs the operator's
A run's job ends at a reviewed, committed change and, when the operator must try it,
a published build. Publishing to a phone, a device or a service is a delivery step
with its own rules.
## Run artifacts
- Every agent visit gets a per-run/step artifacts directory under the data directory.
The directory is passed to the stage as `PIPELINES_ARTIFACTS_DIR` and stated in the
agent prompt next to `Run directory:`; the instruction is to save images,
screenshots, reports and logs there (`references/operations.md`).
- After the visit the server makes one bounded inventory and records each file's name,
size, content type and URL; they appear under the step's `artifacts` in
`inspect RUN_ID --json` and are served at `GET /artifacts/<run>/<step>/<name>`.
- Artifacts are **evidence, not a gate**: an absent, unreadable, symlinked or
oversized file records nothing and never changes the verdict. Never invent an
artifact or claim a stage produced one — the server observes the directory after the
stage.
- An OpenCode-harness stage also gets its real session exported as one file,
`session.html`, in the same directory: bounded (8 MiB source, 2 MiB rendered), with
a visible truncation banner and `session_export.truncated` when cut; the step's
`session_export` records the file. The `session.md` export is retired — never
written, never presented (a run recorded before the change still lists it and every
listing hides it). Export failures and Pi (no native export path) record a
diagnostic and never fail the run or change the stage result.
## Publish a build to the LAN
- When an item builds something the operator should try (an app, a binary, a report),
have the run publish the built file into the **current run's** artifacts directory
and report its LAN URL: `http://<server-host>:<port>/artifacts/<run>/<step>/<name>`.
- **Verify the URL serves the real file** before reporting it; a printed path or an
exit-0 publish is not proof. Fetch it and confirm the bytes are the artefact.
- The phone or client reaches the server at its configured endpoint; never hardcode a
server address into the project. A URL the operator's device cannot reach is not a
delivery.
## Name a WIP so it cannot be mistaken for verified
- Give a not-yet-verified build a name that marks it: `wip-<short-HEAD>` (for example
`myapp-wip-1fece88.apk`).
- **Reserve the plain, unmarked name for the verified build**, so the operator and
later runs can tell at a glance which artefact passed review and which did not.
- Never overwrite or relabel a WIP as verified without the review that qualifies it.
## Install and deploy boundaries
- **Installing onto the operator's physical device is the operator's job, not a
run's.** A run may install only on the device its brief names
(`references/queue.md`).
- **Restarting, rebuilding or reconfiguring the Pipelines/OpenCode service is the
operator's job.** A run may not stop a server another run depends on.
- A run may build and publish; it may not deploy a service, install to hardware the
operator holds, or push or tag a shared branch.
## Drafts, approvals and immutable history
- Delivery still obeys the authoring rules (`SKILL.md`): drafts are retained,
publication creates **immutable** versions, and submission, execution, retry,
cancellation and deletion ask for explicit confirmation.
- `--yes` approves only the specific action you named; it is not approval to publish,
run or schedule. A run must not submit a pipeline or activate a schedule.
## Example (this repository, not a rule)
This repository's Android client is delivered as a debug APK:
- Build and publish the APK into the current run's artifacts directory as
`pipelines-debug-wip-<short-HEAD>.apk` and report the LAN URL, for example
`http://10.0.0.249:8080/artifacts/<run>/1/pipelines-debug-wip-1fece88.apk`. The
plain name is reserved for the verified build.
- Screenshots come from `android/scripts/capture_png.sh -s <serial> <out.png>` (and
`--check <file.png>` to re-validate); it captures on the device, pulls and checks
the PNG magic bytes, deleting a file that is not a real image. Never write
`adb ... screencap` to a file through `exec-out` or a redirect.
- The device serial is named per item in its brief; the operator's attached device is never the
runs' device.
- This is the concrete instance of the general rules above; a different project
substitutes its own build artefact, capture tool and device, and keeps the naming
and boundary rules.