Select PR Routines

Request an edit or new routine

Use the existing PR authoring contract and its JSON template. This dispatches machine-side work using create-routine; the PR author does not need to reserve hardware or implement another authoring workflow.

1. Choose edit for an existing routines/<id>/routine.ts at the selected harness commit, or create with a new stable ID absent at that commit. Pin source.revision to the exact reviewed harness SHA, not the MentraOS PR SHA or a moving branch. Describe the goal, changed or added English steps and observable expected results. For edits, name the affected step IDs and preserve the rest of the flow. The machine verifies the complete saved flow, not just the new step.

2. Choose an enrolled host/lane offering the required platform, glasses models and capabilities. Use an already configured target or ask its owner for the host/lane IDs and prerequisites. If Admin access is already available, its GET /api/admin/test-runs/restoration/list projection for host/lane IDs and platform can help, together with the configured lane's capabilities. Authoring uses mac or android; ordinary catalog/replay uses ios-on-mac or android. Current machine-side intake rejects nonempty requirements.environment. Use [] when no generic environment provider is needed; otherwise report the unsupported prerequisite. Preserve the routine's actual fixture needs. If access or a prerequisite is missing, explain exactly what is needed and ask the owner; do not invent IDs or erase requirements to admit the job.

3. Save the contract's comment to a file, replacing its example values. It must start with <!-- mentra-routine-work:v1 --> and contain exactly one JSON block with no surrounding prose. Keep credentials and private device/account data out of the public brief. The workflow supplies the current PR build and origin; do not put artifact URLs, tokens or build metadata into the comment.

   Validate the draft from the MentraOS checkout without dispatching:

   node --input-type=module - /private/tmp/routine-work-comment.md edit <<'JS'
   import {readFile} from 'node:fs/promises';
   import {parseRoutineWorkBrief} from './.github/scripts/routine-work.mjs';
   const [path, kind] = process.argv.slice(2);
   parseRoutineWorkBrief(await readFile(path, 'utf8'), kind);
   console.log('Valid routine-work brief');
   JS

   Use create as the last argument for a creation request. Validation checks the brief's schema; it does not prove host capabilities or source review.

4. On the open same-repository PR targeting dev or staging, first inspect its comments and labels. There must be one marked brief and one authoring-kind label. If no brief exists, post the file and add the missing matching label (routine-work:edit in this example):

   gh pr comment PR --repo Mentra-Community/MentraOS --body-file /private/tmp/routine-work-comment.md
   gh pr edit PR --repo Mentra-Community/MentraOS --add-label routine-work:edit

   The comment author must be a human account with repository write or admin access, verified through GitHub's collaborator permission endpoint. Comment association labels can vary by credential and do not establish access. An AI using that account's gh login works; a bot-authored brief does not. For an existing request, edit its comment by ID instead of posting a second brief. Read back the comment and labels. Ordinary routine:<id> labels can coexist for other relevant coverage.

5. Follow the request workflow and its updating status comment. Automatic intake uses ROUTINE_WORK_PR_DISPATCH_ENABLED, independently of ordinary replay's gate. When an authorized manual submission is needed, use the same intake:

   gh workflow run request-routine-work.yml --repo Mentra-Community/MentraOS --ref dev -f pr=PR

   Intake requires the current PR's published platform artifact. A waiting-for-build notice means nothing was submitted: the enabled automatic build callback, or the same manual intake after publication, submits the work. Changing the brief, source, target or build creates a new work occurrence. Review corrections should continue the existing machine job rather than redispatching by editing the brief. After source review, require the linked ordinary passing run and recording before reporting coverage as verified. Request ordinary replay of the reviewed source through the existing label/workflow; report pending source preparation or the exact refusal explicitly rather than requiring eager collection publication.

Keep request status honest

• PR dispatch is off unless DEVICE_ROUTINE_PR_DISPATCH_ENABLED is explicitly enabled. Adding labels does not enable that gate. When enabled, the existing request workflow submits routine IDs with exact PR build sources through POST /api/internal/routine-dispatches; Core resolves current Harness main or the optional exact override once, freezes app/routine inputs, and routes source preparation to explicitly configured host/lane bindings. Check its request status and linked result. A preparing, queued, rejected, unavailable or unrecorded request is not a pass. After artifact publication, use the normal request workflow/Admin path for an authorized retry; do not toggle labels or repeatedly dispatch to overcome an explicit denial.
• Existing enabled coverage may run after labeling. For firmware/meeting tests, confirm the request fits the existing authorized fixture and finite attempt budget. If that authorization is unknown, defer adding the label and report the recommendation and missing prerequisite. Do not enable dispatch or increase limits. Installed provider capabilities and current ownership are checked by Core and the host controller; an authorized queued request need not wait for an idle device, and an unavailable fixture must be reported as pending/not-run rather than passed.
• In the PR's validation section, explain the selected replay/edit/create request, the behavior it covers and any missing prerequisite. A recorded pass is required for the passing-example catalog, not for requesting valid main-source coverage. Queued authoring, source ready for review and prepared source are progress states; they are not an ordinary test pass.
• Public PRs contain coverage/status and approved result links, not credentials, account details, private logs, firmware assets or raw recordings.