The wire format

What AISWEC writes on GitHub, and what Suite reads back. One rule decides everything here: formatting is GitHub-flavoured markdown and nothing else. No HTML, no invisible sections, no metadata carrying structure. A person reading the issue on GitHub sees the whole document; Suite sees the same document and knows what each part is.

Seven HTML comments survive, and none of them formats anything: -spec:v1, -questions:v1, -escalate:v1 and -reply:v1 say what a comment is (and -spec:v1 is the anti-spoofing boundary in selectTrustedSpec), -run:v1 carries what a run cost and which engine ran it, -ask:v1 carries the engine a person picked for one task (a provider, a model and an effort, 2026-09-06), -preview:v1 carries where a pull request's preview is (2026-09-06). They are identity and telemetry. Structure is markdown. Suite writes markers of the person's own beside them, and they format nothing either: -done:v1 is their ticks on the manual todos, -from:v1 is where a task came from (2026-09-17), -with:v1 is the other tasks of one ask made in several projects (2026-10-08), -files:v1 is the files attached to a task, a comment or a review (2026-10-09); they are under spec, from, with and files below.

How Suite reads it

comment body
  -> stripMarkerLines            (the six markers vanish)
  -> parseDoc(body, kind)        packages/core/src/protocol/sections.ts
       preface   = everything before the first heading
       plain     = the leading GFM alert in the preface
       sections  = a flat scan of every ## and ### outside a code fence
       key       = REGISTRY[kind]: exact heading, then alias, then prefix
       data      = the shape reader for that key, or undefined
  -> Suite renders a component per key, and plain markdown for anything else

parseDoc never throws. A body with no known heading returns typed: false, and Suite falls back to the markdown it renders today, which is what every comment posted before this format gets. An unknown heading is kept and rendered in document order. A list whose items do not fit their shape, or a table (the shape the format had until 2026-09-05) whose columns were renamed, reads back as undefined and renders as the markdown it is. Nothing is ever dropped.

Shapes

No tables since 2026-09-05: what has rows is a list, one item per row, and the facts a table held are one line. Facts rules: the labels in the registry's order, each followed by its value, the pairs separated by ·, nothing else on the line. Files rules: the path in backticks, the change in parentheses, a colon, the why. Flow rules (2026-10-07): one bullet per path, at most three, the steps joined by → (-> reads back too), at most six, a note in parentheses only where a step needs one, an arrow inside backticks being code and not a join. It was a mermaid diagram until that day, which read as letters and boxes wherever it was not drawn (facts-a-day-backend#31, "no need for A B C D, just arrows and descriptions").

The registry

Headings are matched case-insensitively. Every heading that existed before this format keeps its name, so a Suite that has not deployed yet renders a new comment exactly as it renders an old one.

spec (an issue comment, <!-- aiswec-spec:v1 --> on line 1)

Required: plain, meta, problem, approach, files, criteria. Optional at the wire: schema, flow, try. The engine is told schema is expected whenever a shape changes and flow whenever something moves (2026-09-04, CODE.md's first rule); the parser holds neither against a plan.

Three changes of 2026-10-07, asked for on facts-a-day-backend#31. Schema is Code sketch, since plans put a component's props under it as readily as a table: any code the change turns on, one fence per language, highlighted in Suite. Test plan and Open questions are retired (retired: true): read back from every plan already on GitHub, never in the skeleton. The gates run on every build whatever the plan says, so a fence repeating them told nobody anything, and the tests a plan wants written are the approach's last step; the defaults a plan decided were never questions, and each is said in the approach step it shapes. At a glance lost Checks with them, since it counted the Test plan's commands; a line that still carries it reads back.

Acceptance criteria in a spec are plain bullets, never - [ ]. Ticking a box on GitHub edits the comment, which sets spec.edited and refuses Approve. The finalizer strips a tick if the engine writes one. In a pull request body they are ticks, where editing is harmless.

Manual todos (todos, since 2026-09-06; Your part for a few hours that day, kept as an alias) is what only a person can do: a secret to add, a permission to grant, a token to make, a setting in an account or a store. CODE.md's third rule: never buried in prose. What the bot can write is never one, a workflow file included: the build and revise tokens carry workflows write. In a spec the bullets are bare, for the reason above (the finalizer strips a tick there too); in a pull request body and a reply they are a task list. The ticks live in the person's own comment, <!-- aiswec-done:v1 --> over the same list with its boxes, which Suite creates on the first tick and edits on every one after, and which the engine reads as the maintainer's word on what is done (packages/core/src/protocol/todos.ts). A todo is matched by its words, so the comment may be older than the document. IssueState.todos carries the spec's list with the ticks merged, and Suite refuses Approve while one still blocks.

Two kinds of step do not block (2026-09-17). After facts-a-day-backend#26, whose one todo was a mobile release in another repository that could only happen after the plan it was holding had shipped: a step the engine writes as Follow-up in <repository>: <the change> is work elsewhere, or possible only after this ships, and never blocks; followUp reads the repository and the change back, and stepKey strips the prefix, so the step matches its own words on a plan written before the engine learned it. And a step the person made into a task in another project carries that task under it in the done comment, as one nested line, - Task: owner/repo#n, after this plan is built (or before AISWEC builds it): "after" releases Approve, "before" holds it until the linked task is accepted (closed as completed), and a linked task closed as not planned holds it again, whichever was chosen. An older reader sees the nested line as an unticked step matching nothing, and ignores it. Suite writes the line (taskLine) when it makes or links the task, and parseDone attaches it to the step above it; one above every step belongs to nothing and is dropped. A task carries over a re-run: the spec is written again and only the done comments after it tick its list, but the latest maintainer's done comment before it still names the tasks its steps were made into, and IssueState.todos keeps them by the step's words (carried in manualTodos). ManualTodos.left is what still blocks and done what is ticked; the two differ by exactly the follow-ups and the hand-offs.

<!-- aiswec-done:v1 -->
Manual todos, as they stand:

- [ ] Ship the mobile release that sends the answered ids in the request body instead of the query string: mobile repo, then App Store and Play Store.
  - Task: yusufseyrek/facts-a-day-app#31, after this plan is built

A spec, whole, as the engine writes it:

<!-- aiswec-spec:v1 -->
> [!NOTE]
> The plan arrives as a list you can scan. You see every file it means to touch.

## Implementation Spec

### At a glance

Size M · Files 4 · Contract wire protocol

### Problem

`planSections` lifts one field by regex and hands the rest over as markdown, so Suite cannot
tell a criterion from a paragraph.

### What the docs say

- [EAS Workflows](https://docs.expo.dev/eas-workflows/get-started/): jobs live in `.eas/workflows/*.yml`. Here: `eas.json` profiles only. Missing: the workflow files.

### Proposed approach

1. Add the registry and `parseDoc` in `packages/core/src/protocol/sections.ts`.
2. Read it in `apps/suite/src/github/views.ts`, keeping the heading split as the fallback.
3. Render one component per key in `apps/suite/web/components/Sections.tsx`.
4. Tests in `packages/core/test/sections.test.ts`: a plan of each format reads back typed.

### Affected files

- `packages/core/src/protocol/sections.ts` (add): the parser
- `apps/suite/src/github/views.ts` (edit): reads it, falls back to headings

### Code sketch

```ts
interface Section {
  key: string | null;
  shape: Shape; // new
  data: SectionData; // was: body, the markdown only
}

Flow

• The engine writes the file → the workflow posts it → parseDoc (a heading it does not know stays prose) → Suite renders typed sections

Acceptance criteria

• The plan card shows the files as a list.
• A comment posted before this format renders as it does today.

Try it

1. bun test packages/core Expect: 0 fail.
2. Open a task planned last week. Expect: the page it shows today.

Then the finalizer appends `\n\n---\n\n` and the release footer, which `splitSpecFooter`
already cuts off, and the run line.

### `questions` (an issue comment or inside a reply, `<!-- aiswec-questions:v1 -->`)

The question grammar is unchanged and `parseQuestions` still owns it: `### 1. Question` with
`- (a) option` bullets, one `(recommended)`, `(pick all that apply)` on a heading when several
can be true, at most three questions, never an "other" option. What is new is only the lede.

```md
<!-- aiswec-questions:v1 -->
> [!NOTE]
> You asked for a comparison and the repository has no place for one yet. Tell me what it
> should leave behind and I can plan it.

### 1. What should this task produce?

A file I can check by reading it, or a code change I can test.

- (a) A written comparison in `docs/` (recommended)
- (b) A code change that uses the winner
- (c) Nothing yet, just an answer in the thread

### 2. Which models should I compare? (pick all that apply)

- (a) Opus
- (b) Sonnet
- (c) Haiku

escalate (<!-- aiswec-escalate:v1 -->)

reply (<!-- aiswec-reply:v1 -->)

changed and notes are optional; a reply that only answers a question is the alert alone. A reply may carry a questions block, exactly as revise writes it today.

pr (a pull request body)

## Testing instructions stays as the container heading above ### Automated; it parses as a section with an empty body and Suite renders nothing for it. Closes #n stays last, and the finalizer's ## Preview goes in above it.

## Preview is the finalizer's, never the engine's (2026-09-06). When a repository's .github/aiswec.yml sets preview.web.command, the build and revise stages run it after the engine, on the pushed commit, export preview.web.dir into an Actions artifact, and the finalizer writes the section into the pull request body: one facts line, then the marker line directly under it (no blank line), with the payload the run line's idiom carries (> written as >, the last line of its kind wins, a malformed line reads as absence). The registry marks the entry finalizer: true, so the skeleton the engine copies omits the heading and no prompt names it; parsePreviewLine in packages/core/src/protocol/preview.ts reads the marker, and Suite reads only that. A label of two words (Built from) is read whole because the registry names it; every other label is one word. The finalizer replaces an existing ## Preview section (from its heading to the line before the next ## ), so a body carries one, and a pull request opened before this format carries none: byKey.preview is absent.

## Preview

Link https://yusufseyrek-facts-a-day-app-31.aiswec.com/ · Built from 1a2b3c4 · Status ready
<!-- aiswec-preview:v1 {"pr":31,"sha":"1a2b3c4…","status":"ready","url":"https://yusufseyrek-facts-a-day-app-31.aiswec.com/","artifact":2345678,"run":987654321,"expires":"2026-09-20T10:00:00Z","dir":"web","access":"repository","storage":true} -->

Closes #30

A failed export writes Built from 1a2b3c4 · Status failed · Run https://github.com/…/actions/runs/… over a marker whose status is failed; a stage that exported nothing (no pull request, nothing pushed, previews off) writes no section at all. The host is previewSlug(owner, repo, number): owner and repository lower-cased, every run of anything but a letter or a digit one hyphen, joined with the number by hyphens, and when that passes 63 characters (a DNS label's limit) the repository name is cut and the first six hex characters of the SHA-256 of owner/repo are put before the number, so two cut names stay apart. The same rule is preview_slug in both stage files, and stages.test.ts runs the bash against the library.

The phone is the same line's second half (2026-09-06). With preview.phone: eas in .github/aiswec.yml the build and revise stages publish the pull request's JavaScript as an EAS Update on the branch pr-<n> (eas update --branch pr-<n> --message "<title>", the token from the expo_token secret, in that step's env and nowhere else), which a person's development build (expo-dev-client) opens from a QR. No native build is ever started, and Expo Go is not a surface. The marker gains two members, both absent on a line written before them or by a stage that ran no phone step:

• phone: status (ready, failed, or no-token when no EXPO_TOKEN reached the stage, which is the person's step and not a failure), branch (pr-<n>), group (the update group id), runtime (the runtime version the update was published for), project (the EAS project id), slug (the Expo slug, every character outside [A-Za-z0-9+.-] removed), scheme (the app's own scheme, sanitised the same way), qr (https://qr.expo.dev/eas-update?slug=<slug>&projectId=<project>&groupId=<group>, which is the slug and never the scheme: a development build registers exp+<slug> and qr.expo.dev prefixes exp+ itself, so appScheme names a scheme nothing answers whenever the two differ), link (https://expo.dev/projects/<project>/updates/<group>), launch (the deep link that opens this group in a development build, taken from qr.expo.dev itself with format=url, so the formula lives with Expo and not in a second place here) and platforms (ios, android, or both). Everything but status is nullish, and a null is written as absence, as on the line.
• device (2026-09-06): where the native shell that opens this update lives, so a cloud device can run the change without anyone installing anything. status is ready, or one of four refusals: no-shell (no finished development-client build matches, and a manual todo names the one eas build that would fix it), no-env (preview.phone.env is unset, and a device runs the tenant's real app, so it waits for an environment of its own), public (a public repository, where a shell address and a vendor build id would be world-readable), and failed. Then platform, shell (the EAS artifact address, which the vendor fetches itself, so neither the stage nor the box ever holds the binary), runtime, fingerprint, profile (the eas.json profile whose builds are development clients, which is what makes the shell able to open an update at all), build (the EAS build id) and expires. shell and launch are strings, not URLs, on purpose: a known key whose value fails validation takes the whole line's parse down with it, and a mistyped address must not cost the web preview and the QR. Suite checks the host before handing one to a third party.
• native_touched: whether the change touched ios/, android/, app.json, app.config.*, eas.json or package.json, so the person knows their development build may be too old for the update.

The facts line gains Phone ready, Phone failed or Phone no token, appended after Status when the web preview is on; with the web off and the phone on the line is Built from <sha7> · Status off · Phone ready, and the section is written whenever the export step ran at all. The registry still names Built from and Status as the labels it requires; Phone is one word and reads back like Link does. Under the facts line, when the phone is ready, the finalizer writes for a reader on GitHub: a blank line, then Scan with your development build (runtime <runtime>): ![Phone preview QR](<qr>) on one line, then Update group: <link>, and when native_touched is true one more line, This change touches native code, so the phone preview may need a new development build.; the marker follows the last of them. The facts reader takes the first line only, so these lines stay in the section's body and are never read as facts; Suite draws the phone from the marker, as it draws the web line.

## Preview

Built from 1a2b3c4 · Status off · Phone ready

Scan with your development build (runtime 1.0.0): ![Phone preview QR](https://qr.expo.dev/eas-update?slug=facts-a-day-app&projectId=8b3c5d7e…&groupId=0c3f1a2b…)
Update group: https://expo.dev/projects/8b3c5d7e…/updates/0c3f1a2b…
This change touches native code, so the phone preview may need a new development build.
<!-- aiswec-preview:v1 {"pr":31,"sha":"1a2b3c4…","status":"off","phone":{"status":"ready","branch":"pr-31","group":"0c3f1a2b…","runtime":"1.0.0","project":"8b3c5d7e…","slug":"facts-a-day-app","scheme":"factsaday","qr":"https://qr.expo.dev/eas-update?slug=facts-a-day-app&projectId=8b3c5d7e…&groupId=0c3f1a2b…","link":"https://expo.dev/projects/8b3c5d7e…/updates/0c3f1a2b…","platforms":["android","ios"]},"native_touched":true} -->

Closes #30

When no token reached the stage (no-token), the finalizer adds one line to the body's ## Manual todos (creating the section when absent, once, never twice across revisions): - [ ] Publish the preview to your phone: run `` eas update --branch pr- --message "