# `/wheypoint` bundle commands

`scripts/render_generated_regions.py` generates this file from the static `COMMANDS` manifest in `src/easy_cheese/skills/wheypoint/commands.py`. Do not edit this file. Run each command as `python3 skills/wheypoint/scripts/wheypoint.pyz <command> [args...]`. Each command returns an integer exit status. Pass `--help` to a command for its arguments and output format. Keep worked examples in the skill instructions.

| Command | Purpose | Subcommands |
| --- | --- | --- |
| `checkpoint` | Checkpoint a semantic intent onto the current record |  |
| `handoff` | Render, parse, and dispatch-split handoff preambles | `render`, `parse`, `dispatch` |
| `lint` | Lint a generated projection against the record |  |
| `list` | List every work item under the corpus root |  |
| `log` | Walk the revisions of one work id, oldest first |  |
| `resolve` | Resolve a slug, work id, or path to the current record |  |
| `schema` | Print the JSON Schema for a registered contract slug |  |
| `show` | Print the current record for a work id |  |
| `turns` | Print the user's own turns from a session transcript |  |
| `validate` | Validate an intent against its schema without opening the store |  |

# Wheypoint phase delta contract

This contract covers the durable revision written at the end of the Cook, Press, Age, or Cure phase.
The record is keyed by the phase slug and work id.
A terminal phase handoff writes its phase artifact and then commits one revision for that phase.
Mold publication and Plate publication do not call this writer and do not create a wheypoint revision.
No plugin hook is part of this contract. Issue #654 ask 4 (a `/compact` hook that emits the grounded manifest) is deferred follow-up work until a host-neutral compaction trigger exists; the compaction hook itself is host-specific and out of scope here.

## Entry resolution

Each phase uses its own archive for entry resolution: `python3 skills/<phase>/scripts/<phase>.pyz wheypoint-resolve --ref <slug>`.
Pass `--corpus-root <dir>` to read this project's corpus from another location; the writer accepts the same flag.
A corpus belonging to another project resolves but gates on `project-mismatch`, so the flag relocates a corpus rather than borrowing one.
`--corpus-root` is not accepted with `--legacy`, which reads a note beside the repository rather than any corpus; the pair exits `2`.
Plate also runs this command on entry, but only to resolve; it creates no revision.
The six outcomes are `authoritative`, `not-found`, `legacy`, `gated`, `ambiguous`, and `error`.
An `authoritative` record is the primary input.
Its `working_context` is authoritative and supplies the first batched `tilth_read`.
A `not-found` result proceeds cold.
A `legacy` result shows its source and slug before the phase proceeds.
A `gated`, `ambiguous`, or `error` result stops the phase and shows its payload.
Advisory findings display with any outcome.

A result with `source: phase-artifact` came from the first readable matching file in this order:
`.cheese/cure/<slug>.md`, `.cheese/age/<slug>.md`, `.cheese/press/<slug>.md`, then `.cheese/cook/<slug>.md`.
The handoff preamble parser supplies `phase_slug` from that file.
The result has outcome `legacy` and is not dispatchable as an authoritative record.
Show the source and parsed phase slug before using the artifact as context.

## Grounded context

A phase writer accepts one or more `--grounded path[#start-end]` arguments.
Paths are repository-relative files with optional one-based inclusive line ranges.
A first revision requires at least one grounded entry.
The writer accepts at most 16 grounded entries.
Supplying a grounded list replaces `working_context`; omitting it carries the existing context.
A `#` inside a file name is legal; the range is anchored on the last `#`.
`PR#<n>` and URL entries in `working_context` are pointers, not grounded paths; lint skips them.
The writer anchors relative paths and `.cheese/` at the git toplevel (or `--root`), never at the current directory.

## Writer exit codes

Exit `2` is caller usage: a bad `--grounded` entry or a first revision without one; nothing is written.
Exit `4` is a kernel failure before the artifact write; nothing is written.
Exit `5` means the artifact was written but the revision failed; stderr carries `wheypoint: artifact-orphaned <path>` and the next resolve gates on `stale-artifact-link`.
Every `wheypoint:`-tagged line on stderr is one plain-ASCII line, identical on every host.
A refusal, exit `2` or exit `4`, is reported by the shared CLI as `ERROR: <message>` instead.
A successful write prints `wheypoint: revision work_id=<id> revision_id=<id> revision_number=<n> retried=<bool>`.
A stale-parent retry prints one `wheypoint: retry ...` line and one `wheypoint: retry outcome=...` line.
An unexpected failure always prints a traceback to stderr; set `EASY_CHEESE_DEBUG` or `CHEESE_DEBUG` to add one to deliberate refusals as well.

## Lint findings

`stale-artifact-link` is a gating finding.
It means a digest-bearing phase-artifact link is missing or no longer matches its recorded digest.
Stop instead of dispatching when this finding is present.

`stale-commit` is advisory.
It means the recorded repository commit exists but is not an ancestor of the current `HEAD`.
Display the code and detail with the resolved payload, but do not stop solely for this finding.

`grounded-path-missing` is advisory.
It means a path named in `working_context` is absolute, escapes the repository root, or is no longer a file; the detail names which.
Display the code and detail with the resolved payload, but do not stop solely for this finding.

Advisory findings never hide the outcome.
A gating finding remains a stop even when advisory findings are also present.

# The `CheckpointIntent` contract

`checkpoint` accepts one intent and derives everything else.

Run `schema checkpoint-intent` for the generated JSON Schema.

Run `validate` for a schema-only dry run that never opens the store.

## Shape

```json
{
  "work_id": "auth-retry-backoff",
  "orientation": "One or more lines; the first line becomes the record title at genesis.",
  "working_context": ["src/auth/retry.py", "PR#412"],
  "notes": "The report a cold reader needs, as Markdown.",
  "next": "cook",
  "artifact": ".cheese/specs/auth-retry-backoff.md",
  "entries": [
    {"kind": "decision", "summary": "Cap the backoff at 30s.", "rationale": "Burst callers saturate the pool."},
    {"kind": "directive", "summary": "Prose stays STE100.", "quote": "is it all in STE100?"},
    {"kind": "question", "summary": "Do we jitter?", "blocks_continuation": true},
    {"kind": "blocker", "summary": "Staging is down.", "blocks_continuation": true}
  ],
  "decision_dossier": [
    {"fork": "Ceiling or jitter first",
     "options": [{"option": "ceiling", "evidence": ["src/auth/retry.py:88"], "breaks": "burst callers"}],
     "prior_leaning": "ceiling"}
  ],
  "artifact_links": [{"path": ".cheese/specs/auth-retry-backoff.md", "covers_entry_ids": []}],
  "remove_artifact_links": [".cheese/cook/stale.md"],
  "transitions": [{"entry_id": "q-0f1e2d3c4b5a", "action": "resolve", "rationale": "Answered in the spec.", "target_entry_id": null}],
  "tasks": null,
  "parallel": null,
  "base_revision_id": null,
  "session": {"harness": "claude", "session_id": "abc123", "captured_at": "2026-09-05T12:00:00Z"}
}
```

## Fields

- **`work_id`** is required and becomes one path segment under the corpus.
- **`orientation`** is free text; its first line becomes the title at genesis.
- **`working_context`** is a list of pointers, not a paragraph.
- **`notes`** is the Markdown body the projection renders under `## Notes`; omission carries it forward.
- **`next`** accepts `mold`, `cut`, `cook`, `press`, `age`, `cure`, `affinage`, `briesearch`, `culture`, `hold`, `tasks`, or `done`.
- **`artifact`** rides beside `next`; `affinage` needs `PR#<n>` or a PR URL, and `cook` or `cut` need a path.
- **`entries`** holds `ProposedEntry` values of kind `decision`, `question`, `blocker`, or `directive`.
- Each entry has `{kind, summary, rationale?, quote?, blocks_continuation}`.
- Only a question or a blocker can set `blocks_continuation: true`.
- A `directive` carries the user's words verbatim in `quote`.
- The runtime derives each `entry_id` from the parent and the proposal.
- **`decision_dossier`** holds forks `{fork, options: [{option, evidence, breaks}], prior_leaning}`.
- A fork may describe any active question; every gating entry needs a covering fork.
- **`artifact_links`** holds `{path, covers_entry_ids?}`; the runtime computes the digest and pins the revision.
- A link replaces the carried link with the same path; links are a set keyed by path.
- **`remove_artifact_links`** names carried paths to drop; an unknown path is refused.
- An empty `artifact_links` or `remove_artifact_links` list is refused.
- **`transitions`** holds `{entry_id, action, rationale, target_entry_id}`; `action` is `resolve`, `supersede`, or `withdraw`.
- Only a transition changes a protected entry's state; no operation removes one.
- **`tasks`** and **`parallel`** carry independent moves when `next` is `tasks`; see [`parallel-handoffs.md`](parallel-handoffs.md).
- **`base_revision_id`** pins the revision the intent was written against; omit it to bind the current revision.
- **`session`** holds optional `{harness, session_id, captured_at}`.

## Rules

- Omission carries data forward; `null` means unchanged.
- An explicit empty `working_context` or `decision_dossier` replaces the carried value.
- Identifiers match `[a-z0-9][a-z0-9._-]{0,63}`.
- Text fields contain at most 2000 characters; lists at most 64 items.
- A first checkpoint must carry at least one entry or a `notes` body.
- An unknown key at any depth is refused and named by path.
- Text that matches a credential pattern is refused and named by field.
- An identical intent against the same parent replays the existing receipt.
- A changed intent against a superseded parent is refused as stale.

## Compaction proof

After a context compaction, rehydrate with `show`, then pass `--compacted <proof.json>`.

The proof is a `CompactionRecord`: `{rehydrated_from_revision_id, rehydrated_record_digest, reconciled_entry_ids}`.

`rehydrated_from_revision_id` must equal the current revision and `rehydrated_record_digest` its record digest.

`reconciled_entry_ids` must include every protected entry in the record.

The runtime derives `prior_compaction_revision_id` from stored receipts and refuses a supplied value.

## Reply envelope

Every command prints exactly one JSON object, on one line, to stdout.
A success reply is `{"ok": true, "command": "<name>", ...fields}`.
A failure reply is `{"ok": false, "command": "<name>", "error": {"code": "...", "message": "...", ...extra}}`.

- **`checkpoint`** returns `note_path`, `replayed`, `work_id`, `revision_id`, `revision_number`, `parent_revision_id`, `status`, `durability`, `projection_path`, `record`, `revision`, `markdown`.
- **`validate`** returns `valid` and `work_id`.
- **`schema`** returns `slug` and `schema`.
- **`resolve`** returns `ref`, `outcome`, `dispatchable`, `source`, `work_id`, `record`, `projection`, `findings`, `matches`, `searched`, `legacy_note`, `legacy_slug`, `detail`.
- **`show`** returns `work_id`, `status`, `revision_id`, `revision_number`, `record`.
- **`lint`** returns `path`, `clean`, `findings`, `projection`.
- **`list`** returns `corpus_root`, `items`, and `lines`.
- **`log`** returns `work_id`, `revisions`, `lines`, and `unreadable`.
- **`turns`** returns `transcript`, `count`, `skipped_lines`, `turns`, and `lines`.

`lines` is a list of strings, one per row, for a shell caller to read line by line.
Each `lines` entry is tab-separated columns, in a fixed order per command.
`list` columns are `work_id`, `revision_number`, `status`, `next`, `detail`.
`log` columns are `revision_number`, `revision_id`, `captured_at`, `additions`, `transitions`, `compacted`.
`turns` columns are `timestamp`, `text`.
A column value escapes a backslash as `\\`.
A column value escapes a newline as `\n`.
A column value escapes a tab as `\t`.
This escaping keeps one line one record.

`items` (from `list`) is one untyped JSON object per work item, carrying `work_id` plus either `unreadable`, `no_record`, or the record's summary fields.
`revisions` (from `log`) is one untyped JSON object per revision, carrying `revision_number`, `revision_id`, `captured_at`, `additions`, `transitions`, `compacted`.
`turns` (from `turns`) is one untyped JSON object per user turn, carrying `timestamp` and `text`.
`unreadable` (from `log`) lists `{path, reason}` for revision files the scan could not parse.
`skipped_lines` (from `turns`) counts transcript lines that could not be parsed as a turn.
`count` (from `turns`) is the number of turns returned.
`corpus_root` (from `list`) is the resolved root directory the listing scanned.

Exit `0` means the command succeeded; the reply carries the command's own fields.
Exit `1` means the command refused the request; the reply carries `error.code` and `error.message`.
Exit `2` means the command-line usage was wrong, before any command ran.
Exit `3` means an unexpected internal error; `error.code` is `internal-error` and a Python traceback goes to stderr, never into the JSON.

Each refusal names a `code`:

- `invalid-json`: stdin was not one JSON value.
- `storage-error`: the work store could not be opened or read.
- `commit-only-field`: `checkpoint` was asked to author `compacted`, `compaction`, or `expected_revision_id` directly.
- `invalid-intent`: the intent payload failed schema or delta validation.
- `secret-pattern`: a field looked like a credential.
- `record-unreadable`: the work's record exists but could not be parsed.
- `compaction-proof-unreadable`: the `--compacted` proof file could not be read or parsed as JSON.
- `invalid-compaction-proof`: the `--compacted` proof failed schema validation.
- `genesis-conflict`: a genesis commit collided with an existing record.
- `stale-parent`: the intent's parent revision has moved on.
- `commit-refused`: the commit kernel refused the delta for another reason.
- `note-unwritable`: the note directory or mirror file could not be written.
- `pending-corrupt`: a pending-mirror ledger entry named a different request than its revision.
- `unknown-contract`: `schema` was asked for a slug with no registered contract.
- `record-missing`: `show` or `log` found no record for the work id.
- `store-inconsistent`: `log` found a record but every revision file was dropped as unreadable.
- `session-required`: `turns` was given neither `--session` nor `--transcript`.
- `invalid-session`: the given `--session` id was not a safe file-name segment.
- `transcript-missing`: no transcript file exists at the resolved path.
- `invalid-reference`: `resolve` could not interpret the given reference.
- `internal-error`: an unexpected exception, not a refusal, reached `main`.

# Legacy notes

## Handwritten legacy notes

A handwritten note under `.cheese/notes/` predates the continuity kernel.

The `resolve` command still reads it, and a legacy result is never authoritative.

A legacy result gates a resume for a human decision.

## Header keys

A legacy note accepts `mode:`, `order:`, `session:`, `git:`, `created:`, `parents:`, and `baseline:` between `artifact:` and the orientation.

`mode:` is optional; an omitted mode means `mode: single`.

In `mode: single`, `next:` names the skill that the new agent runs.

For multiple read-only moves, use a `next:` list with `order: parallel | sequential`.

Use only `briesearch` or `culture` in an inline `next:` list.

See [`provenance-fields.md`](provenance-fields.md) for `session:`, `git:`, `created:`, and `parents:`.

## Legacy status values

- `halt: <one-line reason>` is valid only in a handwritten note.
- The runtime never derives `halt`; derived status has only `ok` and `gated:`.
- `resolve` gates every legacy status whose disposition is not `proceed`.
- A legacy `halt` therefore stops: the reader shows the reason and dispatches nothing.

## Baseline

A handwritten note can record a one-line `baseline:` value.

The baseline is settled state; do not re-ask, re-flag, or re-halt on identical baseline entries.

The canonical record carries no baseline field, so keep a Cook baseline mapping in the Cook handoff.

See [`../../cook/references/quality-gates.md`](../../cook/references/quality-gates.md).

## Resume semantics

`/cheese --continue <slug>` resolves the slug through `resolve` and dispatches `next:` only from a validated current revision.

An absolute note path resolves as an explicit path first.

Resume preserves `mode:`, `--hard`, `--open-pr`, `--safe`, and an explicit `--auto`.

Press corrective work remains `continue: press-corrective-cook`, not a global Press-to-Cook dispatch.

# Multi-move handoffs

Use this contract when one checkpoint starts multiple moves.

`tasks` and `parallel` are `CheckpointIntent` fields; see [`intent-contract.md`](intent-contract.md).

Set `next: tasks` and give at least one task.

The projection renders `mode: parallel` between `next:` and `artifact:`, plus a `## Tasks` section.
This position keeps mode metadata separate from free-text orientation.
A legacy orientation that starts with `mode:` remains text.

A single move does not need this contract.

## `parallel` and `tasks`

Give each task its exact `command`; commands can name different skills.

Never run parallel write tasks in one checkout.

Select one isolation strategy:

| `worktree_strategy` | Use when | Required fields |
| --- | --- | --- |
| `existing` | The user has durable bench checkouts | each write task has distinct `worktree`, `branch`, and `branch_from` |
| `create` | No checkouts exist | `worktree_root`, plus each write task has `branch` and `branch_from` |
| `harness` | The host creates isolated worktrees | each write task has `branch` and `branch_from`; the host creates the checkout |

Intent example:

```json
{
  "work_id": "kip-ai",
  "orientation": "KIP-76 and KIP-77 are ready to run as independent PR efforts.",
  "next": "tasks",
  "parallel": {"isolation": "git-worktree", "worktree_strategy": "existing"},
  "tasks": [
    {"slug": "kip-77-ai-test-server", "intent": "cook", "repo": "/path/to/repository",
     "worktree": "/path/to/worktree-01", "branch": "user/kip-77-ai-test-server",
     "branch_from": "origin/main", "command": "/cook .cheese/specs/kip-77-ai-test-server.md"},
    {"slug": "kip-76-ai-service-spin-up", "intent": "cook", "repo": "/path/to/repository",
     "worktree": "/path/to/worktree-02", "branch": "user/kip-76-ai-service-spin-up",
     "branch_from": "origin/main", "command": "/cook .cheese/specs/kip-76-ai-service-spin-up.md"}
  ]
}
```

Rendered projection preamble and tasks block:

```markdown
status: ok
next: tasks
mode: parallel
artifact:
KIP-76 and KIP-77 are ready to run as independent PR efforts.

## Tasks

parallel:
  isolation: git-worktree
  worktree_strategy: existing
tasks:
  - slug: kip-77-ai-test-server
    intent: cook
    repo: /path/to/repository
    worktree: /path/to/worktree-01
    branch: user/kip-77-ai-test-server
    branch_from: origin/main
    command: /cook .cheese/specs/kip-77-ai-test-server.md
  - slug: kip-76-ai-service-spin-up
    intent: cook
    repo: /path/to/repository
    worktree: /path/to/worktree-02
    branch: user/kip-76-ai-service-spin-up
    branch_from: origin/main
    command: /cook .cheese/specs/kip-76-ai-service-spin-up.md
```

For a new setup, use `worktree_strategy: create` and add `worktree_root`.

`/cheese --continue` derives one checkout from each task slug.

## Read-only moves in a legacy note

A handwritten legacy note may list read-only moves with `next: [briesearch "slug1", culture "slug2"]`.

With `order: parallel`, `/cheese --continue` starts one read agent per item in the same turn; with `order: sequential`, it runs them in listed order.

See [`legacy-notes.md`](legacy-notes.md).

# Provenance and lineage

A live session can fill four optional header fields.

Two lineage commands remain outside the continuity contract.

## Provenance fields

Put these optional fields before the orientation line.

Only the live session supplies them.

Pre-provenance notes remain valid.

- **`session: <harness>:<session-id>`** identifies an active Claude, Codex, or OpenCode session.
- Omit the field when it is unavailable.
- Claude's newest-file heuristic is `<speculative>`.
- **`git: <branch>@<short-sha>`** identifies the branch and short commit.
- Use a callable, read-only git inspection capability.
- Run `git status --short --branch` and `git rev-parse --short HEAD`.
- Omit the field when git inspection is unavailable.
- Omit the field outside a git repository.
- **`created: <UTC ISO-8601>`** gives the UTC capture time.
- **`parents: [<slug>, ...]`** gives the lineage that the commands below write.

## Lineage commands

Legacy `--join` writes `parents: [<slugA>, <slugB>]`.

Each `--split` child writes `parents: [<current-slug>]`.

These commands remain outside this continuity contract.

They rewrite `.cheese/notes/` Markdown and commit no delta.