{
  "skill_name": "plate",
  "evals": [
    {
      "id": 0,
      "name": "commit-only",
      "prompt": "Commit these finished changes locally; do not push or open a PR.",
      "expected_output": "Runs final artifact inventory and read-back, then project quality gate, inspects diff, stages named files only, creates a Conventional Commit, verifies status, and stops without asking PR layout or publishing.",
      "files": []
    },
    {
      "id": 1,
      "name": "cohesive-single-auto-selection",
      "prompt": "Open a PR for this finished, cohesive feature and its tests.",
      "expected_output": "Recognizes one cohesive review unit, selects a single PR, and proceeds without asking topology, including under auto.",
      "files": []
    },
    {
      "id": 2,
      "name": "stack-recommendation-choice",
      "prompt": "Open a PR for a change with a shared protocol layer, dependent implementation, and final wiring.",
      "expected_output": "Names the independently reviewable ordered layers, recommends stacked PRs, and asks stacked versus one PR before any commit or branch-layout mutation.",
      "files": []
    },
    {
      "id": 3,
      "name": "explicit-single-authoritative",
      "prompt": "Plate this as one PR.",
      "expected_output": "Treats the explicit single-PR choice as authoritative, skips the topology question, then runs durable-write and quality gates, commits named files, pushes, creates with explicit base/head and --body-file, and verifies via gh pr view.",
      "files": []
    },
    {
      "id": 12,
      "name": "ambiguous-review-shape",
      "prompt": "Open a PR for this finished branch; the changes share a goal but may form separable layers.",
      "expected_output": "Explains the competing cohesion and layer evidence, recommends the best-supported option, and asks single versus stacked before mutation rather than silently choosing.",
      "files": []
    },
    {
      "id": 13,
      "name": "pr-plan-cannot-override-explicit-choice",
      "prompt": "Use one PR. A supplied pr_plan recommends a stack.",
      "expected_output": "Keeps the explicit single-PR choice, skips the topology question, and treats the plan only as non-authoritative review-shape evidence.",
      "files": []
    },
    {
      "id": 4,
      "name": "existing-pr-no-choice",
      "prompt": "Push these fixes to the PR already open for this branch.",
      "expected_output": "Does not ask layout. Detects ordinary versus stack metadata, commits safely, then uses the matching update path and verifies the PR.",
      "files": []
    },
    {
      "id": 5,
      "name": "write-failure-halts",
      "prompt": "Open a PR, but the promised ADR write fails read-back.",
      "expected_output": "Halts before just check, staging, commit, push, or PR creation; reports a {target, backend, verified:false} completion row.",
      "files": []
    },
    {
      "id": 6,
      "name": "hallouminate-fallback",
      "prompt": "Publish this repo; hallouminate is unavailable and the implementation made a durable design decision.",
      "expected_output": "Writes and reads back a tracked docs/adr fallback, includes it in the commit, and does not hand-edit a wiki.",
      "files": []
    },
    {
      "id": 7,
      "name": "graphite-post-merge",
      "prompt": "The bottom Graphite PR merged. Sync and republish the remaining stack.",
      "expected_output": "Uses gt sync, gt log short, and gt submit --stack; never bare rebase or single-branch push.",
      "files": []
    },
    {
      "id": 8,
      "name": "git-town-post-merge",
      "prompt": "The bottom Git Town PR merged. Catch up the rest.",
      "expected_output": "Uses git town sync --stack and git town branch. Conflict recovery uses git town continue/skip, not bare git rebase continuation.",
      "files": []
    },
    {
      "id": 9,
      "name": "gh-stack-post-merge",
      "prompt": "The bottom gh stack PR merged. What should happen locally?",
      "expected_output": "Uses gh stack sync to pull server-cascaded state and gh stack view; submits only for unpublished local commits.",
      "files": []
    },
    {
      "id": 10,
      "name": "stack-without-boundaries",
      "prompt": "Make this a stack.",
      "expected_output": "After the topology choice, asks for commit/file split boundaries rather than inventing them.",
      "files": []
    },
    {
      "id": 14,
      "name": "gh-stack-not-enabled",
      "prompt": "Publish this as a stack. gh-stack is the only installed provider and its repository preflight answers 404.",
      "expected_output": "Reads the stack-tools gh-stack status not-enabled from the read-only repos/{owner}/{repo}/stacks preflight, halts before any stack mutation, and reports the repository-enablement requirement rather than retrying or emulating a stack with plain pushes.",
      "files": []
    },
    {
      "id": 15,
      "name": "gh-stack-preflight-auth-failure",
      "prompt": "Publish this as a gh-stack stack; the enablement preflight answers 401.",
      "expected_output": "Reports an authentication failure, not a repository-enablement requirement, and does not treat the non-200 response as proof that Stacked PRs is disabled.",
      "files": []
    },
    {
      "id": 11,
      "name": "hard-final-state",
      "prompt": "Plate --hard and open a PR.",
      "expected_output": "Runs final writing gate and validation before giving hard-cheese the final artifact inventory and completion rows, then publishes only if the gate passes.",
      "files": []
    },
    {
      "id": 16,
      "name": "malformed-durable-write",
      "prompt": "Plate this work. The durable ADR write was rejected: the replace_text op carried start and end line numbers alongside old and new.",
      "expected_output": "Halts at the durable write step, names the failure plate-owned because replace_text carries only old and new and never start/end, then re-runs the canonical sequence for that file \u2014 fresh tagged read, one stale-safe write with the corrected op shape, diff read-back \u2014 instead of reporting a backend outage, retrying the stale tag, or falling back to a shell redirect or host editor.",
      "files": []
    },
    {
      "id": 17,
      "name": "review-surface-request",
      "prompt": "Plate this branch and tell me whether the diff is safe to merge.",
      "expected_output": "Halts at classify and names the failure plate-owned: the review judgment is /age's, not /plate's, so it never computes a review surface for its own sake. Reports the routing and either proceeds with the publication half alone or stops for the user to route the review, never blending a quality verdict into the completion record.",
      "files": []
    },
    {
      "id": 18,
      "name": "gh-stack-warning-only-failure",
      "prompt": "gh stack submit exited zero but warned that it failed to update the stack on GitHub. Is publication complete?",
      "expected_output": "Treats the warning as publication failure, preserves the command output, and does not report completion until gh-stack-verify confirms every PR base, head, state, SHA, and remote stack mapping.",
      "files": []
    },
    {
      "id": 19,
      "name": "gh-stack-wrong-trunk-recovery",
      "prompt": "This published gh stack was initialized with origin/main as its trunk. Repair it without replacing the PRs.",
      "expected_output": "Rejects origin/main as a remote-tracking trunk, snapshots PR identities and stack state, halts for merged, queued, auto-merge-enabled, or non-open PRs, and otherwise un-stacks and re-adopts the same branches on main before verifying the same PR numbers and exact remote mapping.",
      "files": []
    }
  ]
}

# `/plate` bundle commands

`scripts/render_generated_regions.py` generates this file from the static `COMMANDS` manifest in `src/easy_cheese/skills/plate/commands.py`. Do not edit this file. Run each command as `python3 skills/plate/scripts/plate.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 |
| --- | --- | --- |
| `gh-stack-preflight` | Validate the gh-stack trunk and origin branch before mutation |  |
| `gh-stack-run` | Run one gh-stack mutation and reject warning-only success |  |
| `gh-stack-verify` | Verify exact gh-stack PR and remote stack publication state |  |
| `stack-tools` | Detect supported stacked-PR providers without mutating the repository |  |
| `validate-publication` | Validate terminal publication evidence |  |
| `wheypoint-resolve` | Resolve a phase slug through the shared Wheypoint kernel (JSON out) |  |

# Durable writes

Write every promised artifact. Read each artifact back. Do not publish before both steps finish.
Also write each durable fact that you find during implementation. Read each fact back.

## Inventory

Build one list of required artifacts. Include handoffs, specifications, promised reports, generated files, ADR decisions, domain-model decisions, and release notes.
Include architecture, convention, protocol, or gotcha knowledge that you find during implementation.
Classify each item as required or optional. Classify each item as tracked or transient.

When the repository has a hallouminate wiki, sweep `git status` for uncommitted `.hallouminate/wiki/` paths.
Add each non-gitignored path as a required tracked artifact. Wiki writes from earlier in the session ship with this publication.

## Backend cascade

1. When the consumer repository exposes a hallouminate wiki, invoke the explicit
   user-visible `/wiki-ingest` handoff/capability. Do not duplicate its curation
   algorithm or hand-edit `.hallouminate/wiki`.
2. If hallouminate or `/wiki-ingest` is unavailable, write the tracked fallback
   from `skills/mold/references/adr.md`: `docs/adr/<slug>-NNN.md`. A cumulative
   domain model uses the repository's existing tracked domain-model path.
3. Other promised tracked artifacts go to their contractually named paths.
4. `.cheese/` reports are transient evidence. Keep them unstaged.

## Canonical write sequence

Run these three calls in order for each tracked file:

1. **Fresh tagged read** — Read the target immediately before writing. Copy its tag and 1-based line numbers from that read.
   Never reuse a tag, a line number, or a file body captured earlier in the session.
2. **One stale-safe write** — Send one write with that fresh tag. Use the operation shape that the backend defines.
   A text replacement carries only the exact unique `old` string and its `new` replacement—never `start`/`end` line numbers.
   Line operations carry only integer `start` and `end` values from the fresh read.
   Mixing the two op shapes is a malformed write. It is a call-shape defect owned by this skill, not a backend outage.
3. **Diff read-back** — Re-read the written range or diff the file.
   Compare the target, essential contents, and expected revision. Then mark the row as `verified`.

A rejected write means the file drifted. Read the file again for a new tag. Then retry that section.
After a rejection, never retry with the stale tag. Also, never fall back to a shell redirect or a host editor.

## Verification

Read back every required write from the same backend. Compare the target, essential contents, and expected revision.
Emit one completion row per item in the exact shape `{target, backend, verified}`.
Set `verified` to true only after a successful read-back.

Halt before `just check`, staging, commit, push, or PR creation if a required write is missing.
Also halt if a write fails or a read-back cannot verify it.
Report optional write failures. Never mark them as complete.

## Stack placement

Put shared tracked knowledge on the bottom/common branch or an explicit wiring branch.
All dependent PRs must inherit that branch. Put PR-specific artifacts on the branch whose behavior requires them.
The completion rows must name that placement before you submit the stack.

## `/hard-cheese` handoff

When `--hard` is active, pass one JSON context into `/hard-cheese` before publication.
The context requires four fields:

| Field | Value |
| --- | --- |
| `artifacts` | The completion rows in the exact shape `{target, backend, verified}` |
| `inventory` | The final required and optional artifact list |
| `tracked_diff_digest` | The digest of the tracked artifact diff at the reviewed state |
| `gate` | The quality gate command and its result |

Halt when a field is missing. Halt when a row is unverified.
Compute `tracked_diff_digest` from the reviewed tracked tree. Do not reuse a digest from an earlier state.

# `gh stack` publication

Use this provider only when `github/gh-stack` is installed and the enablement
preflight reports `available`. Run every command from the repository root.

## Contents

- [Inspect the installed command](#inspect-the-installed-command)
- [Validate the trunk before mutation](#validate-the-trunk-before-mutation)
- [Initialize and inspect](#initialize-and-inspect)
- [Guard every mutation](#guard-every-mutation)
- [Publish and verify](#publish-and-verify)
- [Install, authenticate, and detect](#install-authenticate-and-detect)
- [Enablement preflight](#enablement-preflight)
- [Command map](#command-map)
- [Exit handling](#exit-handling)
- [Conflict recovery](#conflict-recovery)
- [Wrong-trunk recovery](#wrong-trunk-recovery)
- [Plate recipes](#plate-recipes)

## Inspect the installed command

Run `gh stack --version` and `gh stack <command> --help` before the first
mutation. The verified command surface adopts existing branches through
positional arguments. Do not use the deprecated hidden `init --adopt` flag.
The installed `init` command has no `--prefix` or `--numbered` flags.

## Validate the trunk before mutation

Resolve the intended GitHub branch name. The default branch query
`gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'` returns a
name such as `main`. Do not pass a remote-tracking value such as `origin/main`
or `refs/remotes/origin/main` to `--base`.

Run the executable preflight before `init`, `link`, or any recovery mutation:

```bash
python3 skills/plate/scripts/plate.pyz gh-stack-preflight \
  --trunk <github-branch-name> --remote origin
```

The preflight canonicalizes `refs/heads/<name>` to `<name>`, validates the Git
branch name, requires the `origin` remote, and confirms the exact
`refs/heads/<name>` branch on that remote. Halt at `publish` when it fails.

## Initialize and inspect

Initialize one or more new or existing branches in bottom-to-top order:

```bash
gh stack init --base <trunk> <bottom> [<next> ...]
```

Existing branches are adopted automatically. Add a new top branch with
`gh stack add <branch>`. Do not use combined staging or commit flags. Stage
named paths and create normal commits before branch operations.

Inspect with `gh stack view --short` or `gh stack view --json`.
Resolve local tracking paths from `GIT_DIR="$(git rev-parse --git-dir)"`.
Tracking lives at `$GIT_DIR/gh-stack`. Rebase recovery state lives at
`$GIT_DIR/gh-stack-rebase-state`. Git does not track either path.

## Guard every mutation

The extension can print `⚠` warnings for failed PR or stack API calls and still
exit zero. A zero exit is therefore provisional. Run mutations through Plate's
guard so a warning, HTTP failure, or non-zero exit fails publication:

```bash
python3 skills/plate/scripts/plate.pyz gh-stack-run -- \
  gh stack <operation> <arguments>
```

The guard requires explicit `--remote origin` for `submit`, `push`, `sync`,
`rebase`, and `link`. The installed `init`, `add`, `modify`, and `unstack`
commands do not support `--remote`; do not add it to those commands.

## Publish and verify

Resolve every title and body before publication. Submit the complete chain:

```bash
python3 skills/plate/scripts/plate.pyz gh-stack-run -- \
  gh stack submit --auto --open --remote origin
```

Here `--auto` skips only the provider editor. It does not override Plate's
explicit topology or review-shape policy. Omit `--open` when the requested PRs
must remain drafts.

Use guarded `gh stack push --remote origin` only to update existing branches
without PR metadata changes. Never use a bare single-branch push.

After `submit`, `push`, or `link`, run terminal validation:

```bash
python3 skills/plate/scripts/plate.pyz gh-stack-verify \
  --trunk <github-branch-name> --remote origin
```

The verifier fails unless all of these facts match exactly:

- The local stack trunk equals the canonical GitHub branch name.
- Every branch exists at the same local, remote, and PR head SHA.
- Every PR is open, has auto-merge disabled, and has the expected base and head.
- Every PR maps to the same open GitHub stack.
- The remote stack base, ordered PR numbers, head refs, states, and SHAs match.

Treat any failed check as a failed publication even when `gh stack` exited zero.

## Install, authenticate, and detect

- Install with `gh extension install github/gh-stack`.
- Upgrade with `gh extension upgrade gh-stack`.
- Use full `gh stack` commands. Do not assume the optional `gs` alias.
- Authenticate through `gh auth login`. The extension uses OAuth.
- Detect installation via `gh extension list`.
- Resolve all local metadata with `git rev-parse --git-dir`.

## Enablement preflight

`GET /repos/{owner}/{repo}/stacks` is a read-only preflight; run it before the
first stack mutation instead of discovering enablement from a failed write.

```bash
gh api --include "repos/{owner}/{repo}/stacks"
```

Classify the response by HTTP status, not by process exit:

| Status | Meaning | Response |
| --- | --- | --- |
| `2xx` | Stacked PRs enabled | Proceed with the provider |
| `404` | Repository enablement requirement | Halt and report that Stacked PRs must be enabled |
| `401`, `403` | Authentication or authorization failure | Halt and report authentication or authorization |
| other | Service failure | Halt and preserve the status and stderr |
| none | Indeterminate repository or network failure | Halt and report the unresolved remote check |

`python3 skills/plate/scripts/plate.pyz stack-tools` runs this preflight. It
reports `available`, `not-enabled`, `auth-required`, `service-error`,
`remote-check-required`, or `not-installed`. Proceed only with `available`.
The report preserves `http_status`, `exit_status`, and `stderr`.

## Command map

| Need | Installed command |
| --- | --- |
| Initialize or adopt | `gh stack init --base <branch> <branches...>` |
| Add top branch | `gh stack add <branch>` |
| Inspect | `gh stack view --short` or `gh stack view --json` |
| Pull collaborator stack | `gh stack checkout <PR-or-branch>` |
| Push branches only | `gh stack push --remote origin` |
| Create or update PRs | `gh stack submit [--auto] [--open] --remote origin` |
| Sync remote and local state | `gh stack sync --remote origin` |
| Cascade local rebase | `gh stack rebase --remote origin` |
| Reorder, drop, rename, or fold | `gh stack modify` |
| Link existing branches or PRs | `gh stack link --base <base> --remote origin <items...>` |
| Remove stack tracking | `gh stack unstack [<stack-number>] [--local]` |
| Navigate | `gh stack up`, `down`, `top`, `bottom`, `trunk`, or `switch` |

`submit --auto` defaults new PRs to draft. `--open` marks new and existing PRs
ready for review. `push` changes branches without PR metadata. `link` creates
the server relationship without adopting local tracking.

## Exit handling

The installed extension defines these codes. Warning-free exit zero still
requires terminal validation.

| Code | Meaning | Response |
| --- | --- | --- |
| 0 | Command returned without a typed error | Reject warnings, then verify exact state |
| 1 | Generic or already-reported error | Preserve stderr and halt |
| 2 | Branch or stack not found | Re-detect or adopt; do not emulate |
| 3 | Rebase conflict | Use provider recovery |
| 4 | GitHub API failure | Preserve the API error and halt |
| 5 | Invalid arguments or flags | Read installed help, correct input, and retry once |
| 6 | Disambiguation required | Select the intended stack or remote |
| 7 | Rebase already active | Continue or abort the provider operation |
| 8 | Stack lock acquisition failed | Wait; do not mutate concurrently |
| 9 | Stacked PRs unavailable | Halt and report repository enablement |
| 10 | Interrupted modify requires recovery | Continue or abort `gh stack modify` |

Unknown non-zero exits fail publication. Preserve the command, code, stdout,
and stderr. Then halt.

## Conflict recovery

Resolve each named path after a rebase conflict. Stage each resolved path.
Run `gh stack rebase --continue` or `gh stack rebase --abort`.
Do not run `git rebase --continue`. The provider must update its recovery state.
For modify conflicts, run `gh stack modify --continue` or
`gh stack modify --abort`.

## Wrong-trunk recovery

Use this transaction when local tracking or published PRs use the wrong trunk.
Preserve PR identity when the stack is safe to rebuild.

1. Stop publication. Save `gh stack view --json`, the remote stack response,
   every branch SHA, and every PR's number, base, head, state, draft state,
   `autoMergeRequest`, and merge-queue state.
2. Halt for a user decision when any PR is merged, queued, has auto-merge
   enabled, or is not open. Do not unstack or rewrite those PRs.
3. Run `gh-stack-preflight` with the corrected trunk. Halt if it fails.
4. Run guarded `gh stack unstack <stack-number>`. Verify each PR remains open
   with the same number and head. Verify each PR-to-stack query returns empty.
5. Run guarded `gh stack unstack --local` only if local tracking remains.
6. Re-adopt the same branches, bottom to top, with guarded
   `gh stack init --base <correct-trunk> <branches...>`. Do not recreate or
   rename an existing PR.
7. Submit with guarded `gh stack submit --auto --remote origin`. Preserve draft
   state; add `--open` only when every recovered PR was ready before recovery.
8. Run `gh-stack-verify`. Compare every PR number with the saved snapshot.

If unstacking, re-adoption, PR identity, or final mapping differs from the
snapshot, halt at `publish`. Do not create replacement PRs automatically.

## Plate recipes

### Create a two-layer stack

1. Run the trunk and enablement preflights.
2. Run guarded `gh stack init --base <trunk> <bottom>`.
3. Write, validate, stage, and commit the bottom layer.
4. Run guarded `gh stack add <top>`. Repeat the transaction for the top layer.
5. Inspect with `gh stack view --json`.
6. Submit through the guard with `--remote origin`.
7. Run `gh-stack-verify` and record every verified PR/base/head pair.

### Update a lower layer

Navigate to the lower layer and create a new commit. Run guarded
`gh stack rebase --remote origin`. Inspect the stack. Use guarded `push` or
`submit` according to whether PR metadata changes. Then verify publication.

### Link externally managed branches

Run guarded
`gh stack link --base <base> --remote origin <branches-or-PRs>`.
This command does not adopt local tracking. Verify the remote stack mapping.

### After a bottom PR merges

Run guarded `gh stack sync --remote origin`. Inspect the stack. Submit again
only when local commits remain unpublished. Do not run `gh-stack-verify` until
the remaining stack is fully open and publishable; merged or queued branches
require lifecycle inspection instead.

# Git Town publication

Use when `git-town` is installed and `git-town.main-branch` is configured.
Lineage lives in local `git-town-branch.<name>.parent` config.

## Mandatory agent mode

Append `--non-interactive` to every state-changing Git Town command and supply
names, parents, messages, and merge choices explicitly. Use `--dry-run` first
for risky sync or reorganization when supported. If required input is missing,
stop and ask; never allow an agent-run command to wait on a prompt.

Start the bottom branch with `git town hack <name> --non-interactive` and
extend with `git town append <name> --non-interactive`. Stage named paths and
create normal new commits; avoid combined all-files or rewrite flags.

Inspect with `git town branch`. Publish the chain with
`git town propose --stack --non-interactive`. Sync/restack with
`git town sync --stack --non-interactive`; use `--no-push` only when
publication is not authorized. Never push one stack branch directly.

## Install, configure, and detect

- Install with `brew install git-town`, `choco install git-town`, or
  `scoop install git-town`; check `git town --version`.
- Configure with `git town config setup`, or set trunk directly using
  `git config --local git-town.main-branch <trunk>`.
- On GitHub, prefer `git-town.github-connector gh` to reuse authenticated CLI
  access; environment tokens are preferable in ephemeral systems.
- Usability requires the executable and a non-empty `git-town.main-branch`.
  Inspect parents with `git config --get-regexp '^git-town-branch\.'`.
- Resolve repository metadata with `git rev-parse --git-dir` when inspecting
  git-owned state; never assume a literal metadata path.

Git Town is forge-agnostic. Configure `git-town.forge-type` when forge
auto-detection is wrong.

## Branch creation, types, and configuration

| Need | Command |
| --- | --- |
| Start bottom from trunk | `git town hack <name> --non-interactive` |
| Extend current stack | `git town append <name> --non-interactive` |
| Insert below current | `git town prepend <name> --non-interactive` |
| Create local-only work | add `--prototype` to hack/append/prepend |
| Record/change parent | `git town set-parent <parent> --non-interactive` |
| Detach as perennial | `git town set-parent --none --non-interactive` |
| Inspect lineage/types | `git town branch` |
| Read a parent | `git town config get-parent [branch]` |
| Rename | `git town rename <name> --non-interactive` |
| Delete | `git town delete --non-interactive`; explicit approval required |
| Interrupted state | `git town status --pending` |

Branch types are `feature`, `prototype`, `parked`, `contribution`, and
`observed`, stored in `git-town-branch.<name>.branchtype`. Long-lived shared
branches belong in `git-town.perennial-branches`. Repository defaults may live
in `git-town.toml`; forge/auth settings use `git-town.forge-type`,
`git-town.github-connector`, and the matching token setting or environment
variable.

Prototype branches remain local until proposed. Do not silently convert a
prototype to a published feature branch.

## Sync variants

| Scope or behavior | Command |
| --- | --- |
| Current branch | `git town sync --non-interactive` |
| Current stack | `git town sync --stack --non-interactive` |
| Every branch | `git town sync --all --non-interactive` |
| Skip trunk/perennial pull-in | `git town sync --detached --non-interactive` |
| Restack locally without push | `git town sync --stack --no-push --non-interactive` |
| Prune branches that become empty | `git town sync --prune --non-interactive` |
| Open/update stack PRs | `git town propose --stack --non-interactive` |

Use `--all`, `--detached`, and `--prune` only when their wider scope or
deletion behavior is intended and verified.

## Ship

`git town ship --non-interactive` merges the current branch through the forge.
`--to-parent` ships into a non-perennial parent; an explicit message can be
provided when required. Prefer the forge UI plus
`git town sync --stack --non-interactive` for routine merges. Run `ship`
through Plate only when the user explicitly requested provider-native stack
shipping, verify the target and merge strategy, and confirm the installed
syntax with `git town ship --help`.

## Conflict recovery

When sync, propose, or ship halts, inspect `git town status --pending`.
Resolve and stage named paths, then use `git town continue`,
`git town skip`, or `git town undo` as directed by the pending operation.
A bare `git rebase --continue` is never correct because it does not advance
Git Town's branch walk.

Git Town can force-update rebased stack branches; coordinate when teammates
also write them. Shared durable writes belong on the bottom/common branch or
an explicit wiring branch before propose or sync.

## Plate recipes

### Create a two-layer stack

1. Run `git town hack <bottom> --non-interactive`.
2. Write common artifacts, validate, stage named paths, and commit.
3. Run `git town append <top> --non-interactive`; repeat for top-only work.
4. Run `git town branch` to verify parents.
5. Run `git town propose --stack --non-interactive`, then verify PR bases.

### Adopt an existing branch

Sync it, set its parent non-interactively, inspect lineage, append branches if
requested, then propose the stack.

### Update a lower branch

Switch to it, create a new commit, then sync the stack non-interactively so
descendants and remote PRs follow.

Squash merges can create phantom conflicts because child history no longer
matches the merged commit. Configure `git-town.auto-resolve` or use a
compatible merge strategy when the repository accepts it. Confirm
version-specific syntax with `git town <command> --help`.

# Graphite publication

Use when `gt` is installed, Graphite tracks the current stack, and
`test -f "$(git rev-parse --git-dir)/.graphite_repo_config"` succeeds.

## Agent-safe discipline

Graphite is interactive by default. Pass `--no-interactive` and supply branch
names, messages, bases, and reviewers explicitly. If an operation still needs
an editor or picker, stop and ask rather than hanging or guessing.

Create branches with `gt create <name>` without all-files commit flags. Stage
named paths, then create a normal new commit. For a tracked branch update,
`gt modify -c -m "<message>"` creates a new commit and restacks descendants.
Bare `gt modify` amends; use it only when the user explicitly requests a
history rewrite. Hooks remain enabled.

Inspect with `gt log short`. Restack with `gt restack`; sync trunk and prune
merged branches with `gt sync`. Submit the whole chain with
`gt submit --stack`. Its lease-aware push is the publication path; do not push
one stack branch separately.

## Install, authenticate, and detect

- Install with `brew install withgraphite/tap/graphite` or
  `npm install -g @withgraphite/graphite-cli@stable`.
- Check `gt --version`; use `gt upgrade` on supported releases.
- Authenticate with `gt auth --token <token>`; ephemeral environments prefer
  `GRAPHITE_AUTH_TOKEN`.
- Initialize once with `gt init`; it records trunk at
  `$(git rev-parse --git-dir)/.graphite_repo_config`.
- The provider is usable only when the executable and resolved marker exist.

## Command map

| Need | Command |
| --- | --- |
| Start/extend a stack | `gt create <name>` |
| Adopt an existing branch | `gt track --parent <parent>` |
| Remove tracking | `gt untrack` |
| Inspect | `gt log short` or `gt ls` |
| Navigate | `gt up`, `gt down`, `gt top`, `gt bottom` |
| Check out | `gt checkout <branch>` |
| New commit + restack | `gt modify -c -m "<message>"` after named staging |
| Restack descendants | `gt restack` |
| Fetch trunk, prune, restack | `gt sync` |
| Submit all PRs | `gt submit --stack` |
| Update open PRs only | `gt submit --stack --update-only` |
| Preview | `gt submit --stack --dry-run` |

Submission may add `--draft`, `--publish`, or explicit reviewers. Retain the
default lease check rather than selecting true force.

## Reorganization

Use Graphite commands so lineage remains correct:

| Need | Command and rule |
| --- | --- |
| Move a branch and descendants | `gt move --onto <parent>` |
| Reorder | `gt reorder`; user-driven editor only |
| Split | `gt split -c`, `gt split -h`, or `gt split -f`; verify every resulting boundary |
| Absorb staged hunks downstack | `gt absorb` after named staging; keep confirmation enabled |
| Fold into parent | `gt fold`; explicit history-rewrite approval required |
| Squash current layer | `gt squash`; explicit history-rewrite approval required |
| Remove branch, keep changes | `gt pop`; explicit destructive approval required |
| Undo last Graphite mutation | `gt undo`; inspect before and after |
| Delete branch | `gt delete`; explicit branch-deletion approval required |

After any split, absorb, move, fold, squash, pop, or undo, inspect
`gt log short`, validate affected layers, and resubmit only after lineage and
commit paths match the approved split.

## Collaboration, frozen branches, and multiple trunks

`gt get <branch>` fetches a collaborator's submitted stack. Retrieved branches
are frozen by default; inspect them without mutation. Use `gt unfreeze` only
after the user confirms ownership/coordination, and `gt freeze` to restore the
read-only collaboration posture. `gt get -U` opts into immediate editability;
never choose it silently.

For repositories with several trunks, add one with
`gt trunk --add <branch>`. Use `gt log --all` or `gt checkout --all` for
cross-trunk inspection, but select the intended trunk explicitly before
creating lineage. Graphite refuses to mutate a branch checked out in another
worktree; report that worktree rather than bypassing the refusal. `gt undo`
history is per worktree.

## Conflict recovery

Resolve and stage each conflicted path by name, then run `gt continue` or
`gt abort`. A bare `git rebase --continue` is never the recovery path because
Graphite must advance its stack metadata. There is no documented `gt skip`;
abort and isolate the branch instead.

## Plate recipes

### Create a two-layer stack

1. From clean trunk, run `gt create <bottom>`.
2. Write bottom/common artifacts, validate, stage named paths, and commit.
3. Run `gt create <top>`; repeat the per-layer transaction for top-only work.
4. Inspect with `gt log short`.
5. Publish with `gt submit --stack` and verify every PR/base pair.

### Update a lower layer

Check out the lower branch, stage named paths, create a new commit with
`gt modify -c`, run `gt restack`, inspect, then `gt submit --stack`.

### After the bottom PR merges

Run `gt sync`, inspect `gt log short`, then submit only if local commits
remain unpublished.

Shared durable writes belong on the bottom/common branch or an explicit wiring
branch. Confirm version-specific syntax with `gt <command> --help`.

# Ordinary PR publication

Use this path only after the final writing gate, the green quality gate, named-file
staging, the commit, and the commit verification.

## New PR

1. Confirm that `/plate` resolved the new PR as single. Accept an explicit choice, cohesive-shape inference, or a user answer.
2. Resolve the trunk and current branch. Reject publication from the trunk.
3. Draft a title and body per `## Body contract` below.
4. Write the body to a temporary or transient file. Pass that file through `--body-file`.
   Do not embed a markdown heredoc in `--body`.
5. Push the named branch without force.
6. Create the PR with an explicit base and head:

   ```bash
   gh pr create --title "<title>" --body-file <body-path> --base <base> --head <head>
   ```

7. Verify with `gh pr view --json number,url,title,baseRefName,headRefName,state`.

Do not use `--fill` when it would omit artifact or verification details.

## Existing ordinary PR

Detect the PR with `gh pr view --json number,baseRefName,headRefName,url`. Then inspect the provider metadata.
A stacked topology leaves this file for `stacks.md`. Do not ask the layout question.
Read the base and head with `gh pr view`. Commit the validated named files.
Push the exact head branch. Then read the PR back.
Update the title or body only when the new work makes existing metadata inaccurate.

## Failures

Authentication or permission failures halt publication. Report the exact command and error.
A rejected push does not permit a force-push. Fetch and explain the divergence.
Never create a duplicate PR when one already exists.
## Metadata and lifecycle

Publication-relevant GitHub operations remain here:

- Add `--draft` when explicitly requested.
- Add `--reviewer <login>` or `--assignee <login>` only from the supplied
  publication metadata.
- Use `gh pr edit <number> --title <title> --body-file <path>` when verified
  commits make existing metadata inaccurate.
- Use `gh pr ready <number>` only when asked to publish a draft.
- Use `gh pr checks` to verify publication context. CI triage, review, comments,
  and merge remain `/gh`.

Query the current head for an existing PR before creation.
If a PR exists, switch to the existing-PR path. Do not rely on a failed create call.

## Body contract

Record the purpose, user-visible behavior, non-obvious changes, gate results, durable artifact rows, risks, follow-ups, and stack relationships.
When the repository tracks `.github/PULL_REQUEST_TEMPLATE.md`, use its section headings.
Keep the body file transient unless the repository tracks PR templates or release artifacts.
Leave a transient body file unstaged after verification.

Write for the reviewer's verification pass:

- A semantics-preserving change says so in its first line. It names the mechanism and states the invariant to verify.
  Examples include a behavior-preserving refactor, an internal move, an internal rename, or a formatting-only change.
  Verify unchanged behavior. Add a mechanism-specific check. For example, verify that a move drops nothing and duplicates nothing.
  This check tells the reviewer to scan for accidental semantic drift. The reviewer does not infer intent line by line.
- A semantics-altering change names the changed behavior or contract. It also names its observable verification.
  This information directs scrutiny to the changed logic.
- A change that is not self-contained links its context. Link the spike branch, plan, or stack siblings that show the abstraction in use.
- A `## Non-obvious changes` section names every hunk whose intent is not visible from the diff alone, with one line of reason each.
  Write `None` when every hunk is self-evident. Author-annotated reviews carry markedly lower defect density (Cisco review data).

## Push verification

Read the remote and upstream before pushing. Push the exact named head branch.
Verify local status. Verify the PR head and base.
A successful CLI exit without a matching PR head SHA is incomplete.

# Stack maintenance

Load this reference for the **stack maintenance** mode. Also load it for any new or
existing pull request whose resolved topology is stacked.
Ordinary single pull request work never reads this file.

## Per-layer stack transaction

1. Select the configured provider. Then read its reference.
2. Require explicit split boundaries. Partition paths and commits by layer.
   Place shared durable writes on the bottom/common layer or an explicit wiring layer.
   Classify the production implementation decision. Tests, docs, and durable artifacts inherit its layer.
   They inherit the layer when they directly verify or describe the decision.
   Each layer's implementation preserves semantics or alters them, never both.
   Each layer's pull request body follows `ordinary-pr.md` § Body contract, including `## Non-obvious changes`.
   Put semantics-preserving layers below the semantic changes that depend on their reorganization.
3. Create or adopt provider lineage in the approved bottom-to-top order.
4. Read the spec's `landing.per_layer_green` before publishing any layer.
   `required` (the default) means every layer's quality gate must pass before the
   next layer is published. `tip-only` means only the top layer's gate must pass
   before the chain is submitted; a lower layer's gate failure does not block it.
5. For **each layer**, bottom to top:
   1. Check out its provider-tracked branch.
   2. Run the final writing gate for that layer. Then read every write back.
   3. Run the repository quality gate.
   4. Inspect the layer diff. Then stage only its named paths.
   5. Create a new Conventional Commit without skipping hooks.
   6. Verify the commit's paths and the layer's parent.
6. Inspect or restack the complete chain through the provider.
7. Submit the complete chain after you verify all layers.
8. Read back every PR, base and head pair, and provider stack map.

Never manufacture split boundaries. Never move a shared artifact to a convenient upper layer.
Never submit a partially verified chain.

## Stack provider detection

Resolve metadata through `GIT_DIR="$(git rev-parse --git-dir)"`. Never assume
that the repository metadata directory is the literal `.git` path.

| Provider | Installed | Repository signal | Reference |
| --- | --- | --- | --- |
| Graphite | `gt --version` | `$GIT_DIR/.graphite_repo_config` | [`gt.md`](gt.md) |
| Git Town | `git town --version` | `git-town.main-branch` config | [`git-town.md`](git-town.md) |
| `gh stack` | `gh extension list` contains `github/gh-stack` | `gh api --include "repos/{owner}/{repo}/stacks"` preflight | [`gh-stack.md`](gh-stack.md) |

Use the `stack-tools` report on every invocation. Preserve the provider that already tracks the branch.
When no provider tracks it, use the report's `recommended` provider. State the choice.
Only a `gh-stack` status of `not-enabled` (preflight `404`) is a repository enablement requirement.
Other non-`available` statuses are environment failures. Exit code 4 remains the fallback.
Stop with setup instructions when no provider is usable after you select stacked.
Do not emulate stacking with plain pushes.

## Existing stacked PR updates

Use `gh pr view --json number,baseRefName,headRefName,url` to detect the PR.
Then inspect the provider metadata. Use the per-layer transaction when the topology is a stack.
Use the provider submission process. Never use a bare single-branch push inside the stack.
An ordinary PR uses the generic transaction and `ordinary-pr.md` instead.

Run a provider-native stack merge in `/plate` only when the user explicitly requests the merge.
Require explicit user authorization for a force-push outside a provider's lease-safe stack flow.

# New-PR topology policy

Load this reference for the **topology preflight** and **new PR** modes. It resolves only the review shape.
Execution continues in `ordinary-pr.md` for a single PR or in `stacks.md` for a stacked chain.

For a **new PR**, resolve topology before any commit or branch-layout mutation:

1. Honor an explicit user choice from the current request, verified workflow state, or the spec's `landing` block. It is authoritative.
   Derive the topology from `landing.shape` via `easy_cheese_schemas.manifest.plate_layout_for`, with `landing.layers` as the proposed layer boundaries.
   Persist the choice. Skip the topology question.
2. Otherwise inspect the finished work's review shape:
   - First classify each production change.
     Use **semantics-altering** for features, fixes, or externally observable contract changes.
     Use **semantics-preserving** for behavior-preserving refactors, internal moves, internal renames, or formatting-only changes.
     A diff containing both is never one review unit. Preserved behavior and changed behavior require different review scrutiny.
     Put incidental fixes in a separate change. Never put them in a feature or fix.
     A move or rename is semantics-altering if it changes an externally observable name, path, API, or configuration key.
     Use the same classification for a changed serialized shape, command, or documented contract.
   - Size never decides the shape on its own. It decides whether the question gets asked.
     When the semantics-altering surface exceeds roughly 400 changed code lines, always ask the single-versus-stacked question in step 3, even when the change reads as cohesive.
     Reviewer defect detection falls off sharply past that size (SmartBear/Cisco review data).
     At topology preflight, before a diff exists, estimate the surface from the spec or curd plan. Re-evaluate on the real diff at publication.
   - Choose **single** when the change is one cohesive review unit under that ceiling. Then proceed without asking.
     Its implementation, tests, docs, and durable artifacts must serve one behavior or contract.
     A split must not leave incomplete behavior. It must not force reviewers to reconstruct the whole.
   - Recommend **stacked** when the change has independently reviewable ordered layers.
     Give each layer a named purpose, its own validation, and a stable boundary.
     A lower layer must stand alone. Later layers must build on it without unrelated concerns.
     A change is also stack-sized when one review would combine distinct concerns with clear ordered boundaries.
     Put a semantics-preserving layer below a semantic change that depends on the reorganization.
     Over the ceiling with no layer boundary, recommend single, state the size risk, and still ask.
3. Ask one single-versus-stacked question when you recommend a stack, when the surface exceeds the ceiling, or when the review shape is genuinely ambiguous.
   For a stack recommendation, name the proposed layers. Recommend **Stacked PRs**.
   For ambiguity or an over-ceiling single, state the competing evidence. Recommend the best-supported option.
   Do not choose silently.
4. When a `landing` block exists and the finished diff cannot meet its shape, ask one question that names the layer and the files in conflict.
   A layer that depends on files a later layer owns, or commits that cannot split on the layer boundaries, is a conflict.
   Offer three options: collapse to a single PR, re-layer on the proposed boundaries, or stop.
   Never ask the plain layout question while a `landing` block exists.

This policy stays unchanged under `--auto`. Transport any required question
through
[`../../cheese/references/ask-user-question.md`](../../cheese/references/ask-user-question.md).

```yaml
question:
  id: plate-layout
  prompt: How should this work be plated for review?
  recommended: <single | stacked>
  multi: false
  options:
    - id: single
      label: Single PR
      description: Keep the cohesive change as one branch and one review unit.
    - id: stacked
      label: Stacked PRs
      description: Split the named layers into ordered branches and dependent PRs.
```

## Answer normalization

The transport preserves an `Other` answer. It returns free text with an `other:` prefix.
Read the returned answer. Then apply these rules:

- Map the answer to `single` or `stacked` only when its text is unambiguous.
- Ask one clarification question for every other answer. Offer the same two options.
- Halt at `topology` when the clarification is also ambiguous. Report the answer.
- Persist only `single` or `stacked`. Never persist free text.

A supplied `pr_plan` is evidence for a stack recommendation. It can provide explicit commit and file boundaries.
It cannot override an explicit user choice or another verified topology resolution.
Ask for the split when stacked has no clear user or plan boundaries.
Do not invent the boundaries.

A prior `/plate` **topology preflight** for the same run is the resolution.
The resolution can be explicit, inferred as cohesive, or confirmed after a question.
Persist it as `plate_layout: single | stacked` in workflow state. Choose the `pr_plan` `shape` from this resolution. `plate_layout_for` projects `plate_layout` from `shape`, not the other way. The v1 plan never carries `plate_layout`.
At terminal publication, verify that both values agree. Reuse the resolution. Do not ask twice.
Apply this policy again when the record is missing, conflicting, or unverified. Do not ask automatically.

For an **Existing PR**, detect its ordinary or stacked topology. Do not ask the layout question.
Preserve that topology. Use its matching update path.
Commit-only isolated workers also do not ask because publication is out of scope.

Topology preflight persists the resolution. It reads the resolution back.
It stops before any commit, branch mutation, push, or PR operation.

## Repair-worktree topology

The branch name is `worktree-agent-repair-*`. Apply the policy above to any other branch.

The repair handoff must carry `run_branch`. This field names the verified run branch.
Halt at `topology` when `run_branch` is absent. A missing field is not evidence of a deleted branch.

Then run the mechanical file-overlap check.
See [`../../cook/references/quality-gates.md`](../../cook/references/quality-gates.md) § Repair pathway.
Compute the overlap with one command:

```bash
git diff --name-only --find-renames "$(git merge-base <run-branch> <repair-branch>)" <repair-branch>
```

Compare that path set with the same command run for `<run-branch>`. The shared paths are the overlap.
Count the changed lines of each shared path with `git diff --numstat` over the same range.
Count a rename as its changed lines only. Count a binary path as one changed line.
Halt at `topology` when `--numstat` reports `-` for a path that is not binary.

Then select the topology:

- Publish an ordinary independent pull request against `main` when there are no shared paths.
- Verify branch deletion with `git rev-parse --verify <run-branch>` before you use the independent path for a missing run branch.
  Halt at `topology` when the command cannot decide.
- Move shared files onto the run branch at or below the small-repair threshold. Do not publish these files independently.
  Cook owns the harvest command. Run the harvest through `/cook`.
  See [`../../cook/references/quality-gates.md`](../../cook/references/quality-gates.md).
  Resolve `<run-worktree>` from verified Git worktree state. Halt at `topology` when the harvest fails.
- Restack with the repair as the base pull request above the threshold. Use the stack process in `stacks.md`.