@qvac/harness 0.2.5 → 0.2.7

package/.claude/skills/asana/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: asana
+description: Conventions for the QVAC Assistant Asana board when working through the Asana MCP server — what the MCP cannot do and what that silently breaks, the Context field that decides whether a task is visible at all, and the rule against consuming task descriptions. Use before creating, moving, or reading any Asana task for this project.
+---
+
+# Asana — QVAC Assistant board
+
+Asana work here goes through the **Asana MCP server**. This skill is not a tool;
+it is the handful of things the MCP does not tell you and will not stop you
+getting wrong.
+
+- Workspace `45238840754660` (tether.to)
+- Project `1214754188814246` (QVAC Assistant)
+- Board: <https://app.asana.com/1/45238840754660/project/1214754188814246>
+
+## Do not create tasks through the MCP
+
+`asana_create_task` takes `resource_subtype` of only `default_task`, `milestone`
+or `approval`, and neither it nor `asana_update_task` accepts `custom_type` or
+`custom_type_status_option`. This board runs on the **QVAC Basic Task** custom
+type (`1214533632534265`), whose status options _are_ the workflow — the project
+has one real section and tracks status entirely through the custom type.
+
+So an MCP-created task is a plain default task that:
+
+- is not a `QVAC Basic Task`,
+- has no status (To Do / In Progress / In Code Review / Blocked /
+  Completed-Ready for QA / Fully Verified / Closed-Won't Fix), and
+- cannot be given one afterwards through the API.
+
+It lands on the board looking almost right and is undriveable. **Ask the user to
+create the task in the Asana UI**, where the custom type is the default, and then
+use the MCP to fill fields or comment on it. Do not create it yourself and
+promise to "fix the type later" — the API has no route to do that.
+
+Moving a task's status has the same limitation: the status lives on
+`custom_type_status_option`, which the MCP cannot set. Status changes are a UI
+action.
+
+## Context is mandatory, and the MCP will not warn you
+
+The project's Dev Board tabs are saved views filtered on the **Context** custom
+field. A task with Context unset appears only in "Full List" and "Overview" — it
+is invisible on every Dev Board tab and silently slips off the team's radar.
+
+Whenever you set fields on a task, set Context. Field `1214754188814251`:
+
+| Value          | GID                | For                                               |
+| -------------- | ------------------ | ------------------------------------------------- |
+| `harness`      | `1214754188814252` | engine, mesh and sync, storage, build and release |
+| `integrations` | `1214754188814253` | assistant runtime, agents, tools, skills          |
+| `other`        | `1214758268571416` | genuinely cross-cutting: org, legal, product docs |
+
+Surface which one you picked and why, and let the user correct it. Never guess
+silently, and never leave it blank to avoid choosing.
+
+## Release grouping
+
+Each Dev Board tab groups by **QVAC Workbench Release** (field
+`1214111405360914`) first. A task with none lands in an "Untitled" bucket at the
+bottom of every tab. Default to `tbc` (`1214757840453965`) when the release is
+undecided.
+
+**That field is the app's release, not a package version.** `@qvac/harness`,
+`@qvac/core` and `@qvac/skills` each ship their own `0.x` line; putting one of
+those numbers here files the task against a release that does not exist.
+
+## Never consume task descriptions
+
+Work from task metadata only: GID, name, permalink, completion state, assignee,
+memberships, custom fields, custom type and status, timestamps, and comments.
+
+- `asana_get_task` returns the description by default. Pass an explicit
+  `opt_fields` list that omits `notes`, `html_notes` and `description`.
+- Do not use Asana full-text search as a fallback — it matches descriptions.
+  Find tasks by the QVAC custom field (`1209150993228635`, text) or by GID.
+- If the user wants you to act on a description, ask them to paste the relevant
+  excerpt rather than fetching it.
+
+## Before any mutation
+
+Show the exact change and wait for a yes. That includes field edits, comments and
+completion — this board is shared with the whole team, and a comment cannot be
+unsent.
+
+Never put tokens, secrets or internal-only URLs in a task or comment.

package/.claude/skills/gh-stack/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: gh-stack
+description: >
+  Manages stacked PRs and splits multi-part work into reviewable branches with gh-stack.
+  Use for stack creation, viewing, edits, push, submit, sync, rebase, merge, or checkout;
+  when asked to split or isolate work for review; whenever a user mentions a stack,
+  branch layers, dependent PRs, or gh stack; or when a stack is checked out.
+metadata:
+  author: github
+  version: '0.1.0'
+---
+
+# gh-stack
+
+`gh stack` is a [GitHub CLI](https://cli.github.com/) extension for stacked branches and pull
+requests. A stack is an ordered chain of branches rooted on a trunk, where each branch has one PR
+based on the branch below it, so a reviewer sees only that layer's diff.
+
+`gh stack` prints a stack trunk-first, left to right:
+
+```
+(main) <- auth <- api <- frontend
+```
+
+Left is the **bottom**, right is the **top**. `auth` is based on `main` and merges first;
+`frontend` merges last. `up` moves toward the top, away from trunk; `down` moves toward it.
+Foundational work belongs at the bottom, code that depends on it above. For how to choose the
+layers, read `references/stack-design.md`.
+
+## Setup
+
+```bash
+gh extension install github/gh-stack
+git config rerere.enabled true         # remember conflict resolutions
+git config remote.pushDefault origin   # required if the repo has more than one remote
+```
+
+## Non-interactive use
+
+`gh stack` branches on whether **stdout is a TTY**. Piped, most commands error cleanly or print
+static text; under a PTY the same commands open a prompt or a full-screen TUI and block forever.
+Agent harnesses differ, so always pass the flags below instead of relying on that detection.
+
+**Multiple remotes:** never run `push`, `submit`, `sync`, `rebase`, or `link` without
+`--remote <name>` unless `remote.pushDefault` is configured. `checkout` and `trunk` have no
+`--remote` flag and require the config.
+
+| Always run                                | Never run bare      | Why                                           |
+| ----------------------------------------- | ------------------- | --------------------------------------------- |
+| `gh stack view --json`                    | `gh stack view`     | opens a TUI under a PTY                       |
+| `gh stack submit --auto`                  | `gh stack submit`   | prompts for a title per new PR                |
+| `gh stack merge <target> --yes`           | `gh pr merge`       | `gh pr merge` cannot merge a stack            |
+| `gh stack init <branch>...`               | `gh stack init`     | prompts for branch names                      |
+| `gh stack add <branch>`                   | `gh stack add`      | prompts for a name, and fails even when piped |
+| `gh stack checkout <target>`              | `gh stack checkout` | opens a selection menu                        |
+| `gh stack up` / `down` / `top` / `bottom` | `gh stack switch`   | `switch` is menu-only                         |
+| —                                         | `gh stack modify`   | TUI-only, no non-interactive path             |
+
+- `view --short` is safe in both modes, but it is formatted for humans. Use `--json` to parse.
+- **`checkout <pr>` when a different local stack already covers those branches** cannot be forced.
+  Run `gh stack unstack --local` first (this keeps the stack on GitHub), then retry.
+
+## Branch placement
+
+- **Starting multi-part work:** create the stack before writing files. Do not implement every
+  concern on trunk and split it later. Put one dependent concern in each layer, bottom to top.
+- **Editing an existing stack:** check out the layer that owns the change before editing. Never
+  commit a lower layer's concern on the current top branch. Run `gh stack view --json`; if
+  ownership is unclear, inspect `git log --all -- <path>`. Then check out the owner, edit, commit,
+  rebase upstack, and return to top.
+
+```bash
+gh stack down                   # or: gh stack checkout api
+git add ... && git commit -m "Add get-user endpoint"
+gh stack rebase --upstack       # replay every branch above onto the change
+gh stack top                    # return to where you were
+gh stack push
+```
+
+## Core loop
+
+```bash
+gh stack init auth              # create the stack and check out its branch
+git add ... && git commit -m "Add auth middleware"
+gh stack add api                # next layer, branched from the current one
+git add ... && git commit -m "Add API routes"
+gh stack submit --auto          # push every branch and open draft PRs
+gh stack view --json            # confirm
+```
+
+Add `--open` to `submit` to create PRs ready for review instead of drafts. Branch names are
+verbatim — `gh stack add refactor/foo` creates `refactor/foo`.
+
+## Staying in sync
+
+```bash
+gh stack sync                   # fetch, reconcile with GitHub, rebase, push, refresh PR state
+gh stack sync --prune           # also delete local branches for merged PRs
+```
+
+Pruning never happens without `--prune` when non-interactive. If the local and remote stacks have
+diverged, `sync` prints both chains, makes no changes, and exits 0 with `Sync aborted` — see
+`references/troubleshooting.md`.
+
+## Merging
+
+Scope the merge with an argument:
+
+```bash
+gh stack merge 42 --yes          # PR #42 plus every unmerged PR below it
+gh stack merge 7 --yes           # every unmerged PR in stack #7
+gh stack merge 42 --yes --squash # or --merge, --rebase, --merge-method <method>
+```
+
+Pass a PR number to merge that PR and every unmerged PR below it, or a stack number to merge every
+unmerged PR in that stack. The operation is all-or-nothing: if any PR in that set cannot merge,
+none do.
+
+Without a method flag the last-used method is reused. If the base branch uses a merge queue, the
+stack is queued instead and the queue picks the method, ignoring any flag you passed with a
+warning; queued PRs may land in separate groups.
+
+## Reading state
+
+`gh stack view --json` writes JSON to **stdout**. Status messages go to **stderr** — do not parse
+them, branch on exit codes instead.
+
+```
+trunk           string
+currentBranch   string
+branches[]      name, head, base, isCurrent, isMerged, isQueued, needsRebase
+branches[].pr   number, url, state ("OPEN" | "MERGED" | "QUEUED"); absent when no PR exists
+```
+
+`base` is the saved SHA of the parent branch that this branch was last known to contain. It may be
+older than the parent's current tip. `needsRebase` is true when the current parent tip is no longer
+an ancestor of the branch.
+
+## Exit codes
+
+| Code | Meaning                    | Recovery                                                   |
+| ---- | -------------------------- | ---------------------------------------------------------- |
+| 0    | Success                    | —                                                          |
+| 1    | Generic error              | Read stderr                                                |
+| 2    | Not in a stack             | `gh stack init`, or `gh stack checkout <target>`           |
+| 3    | Rebase conflict            | Follow the Exit 3 recovery below                           |
+| 4    | GitHub API failure         | Check `gh auth status`, retry                              |
+| 5    | Invalid arguments          | Fix the invocation; see `<command> --help`                 |
+| 6    | Disambiguation required    | Branch is in several stacks; check out a non-shared branch |
+| 7    | Rebase already in progress | `gh stack rebase --continue` or `--abort`                  |
+| 8    | Stack file locked          | Another `gh stack` process is writing; retry after ~5s     |
+| 9    | Stacked PRs unavailable    | Not enabled on the repository; tell the user               |
+| 10   | Modify recovery required   | `gh stack modify --abort`                                  |
+
+**Exit 3 recovery:**
+
+- After `gh stack rebase`: resolve the files, run `git add`, then
+  `gh stack rebase --continue`; use `gh stack rebase --abort` to restore the stack.
+- After `gh stack sync`: the stack has already been restored. Run `gh stack rebase` to recreate the
+  conflict, then resolve and continue as above.
+
+## Constraints
+
+- Stacks are strictly linear: one parent, at most one child. Use separate stacks for parallel work.
+- There is no non-interactive reorder or removal. Errors may suggest `gh stack modify`, but it is
+  TUI-only — restructure with `unstack` then `init` instead.
+- PR titles and bodies are auto-generated. Use `gh pr edit` afterwards to change them.
+
+## More detail
+
+`gh stack <command> --help` is authoritative for flags and arguments. Note that
+`gh stack help <command>` does **not** work — it prints the top-level help.
+
+Open the reference whose trigger matches the task; no need to preload all three.
+
+- `references/stack-design.md` — read before creating a stack, when deciding how many layers to
+  use, what belongs in each one, or whether work belongs in a new stack.
+- `references/commands.md` — read when a command fails unexpectedly or you need its preconditions,
+  side effects, atomicity, or ordering guarantees.
+- `references/troubleshooting.md` — read on a rebase conflict, after a squash-merge, on local and
+  remote divergence, when restructuring a stack, or when driving stacks from another tool.

package/.claude/skills/gh-stack/references/commands.md

@@ -0,0 +1,177 @@
+# Command behavior
+
+`gh stack <command> --help` is authoritative for flags and arguments. (`gh stack help <command>` only prints the top-level help.) This file only covers behavior `--help` does not
+explain: preconditions, side effects, atomicity, and failure modes.
+
+## Contents
+
+- [init](#init)
+- [add](#add)
+- [push](#push)
+- [submit](#submit)
+- [link](#link)
+- [sync](#sync)
+- [rebase](#rebase)
+- [view](#view)
+- [checkout](#checkout)
+- [unstack](#unstack)
+- [merge](#merge)
+- [Navigation](#navigation)
+
+## init
+
+Creates the stack and checks out the **last** branch in the list, so a single `init` can lay down
+the whole chain: `gh stack init auth api frontend`.
+
+`init` processes branch arguments from bottom to top. Existing branches are adopted. If the first
+branch does not exist, it is created from the trunk; each later new branch is created from the
+branch immediately before it. There is no separate adopt mode — existence decides. `--base`
+selects a non-default trunk.
+
+`init` also enables `git rerere`. Under a TTY the first run in a repo asks for confirmation; set
+`git config rerere.enabled true` beforehand to skip it.
+
+## add
+
+- **Must run from the top branch** of the stack (or the trunk when the stack is still empty).
+  Anywhere else it exits **5** with `can only add branches on top of the stack`. Run `gh stack top`
+  first.
+- **Uncommitted changes carry over.** Without `-Am`, `add` does not touch the working tree, so
+  staged and unstaged changes follow you onto the new branch. Commit or stash first for a clean start.
+- **`add -Am` commits in place when the current branch has no commits yet** — for example
+  immediately after `init` — instead of creating a branch. This is deliberate: the first layer
+  usually needs its content before a second layer exists.
+- `-A` and `-u` are mutually exclusive, and both require `-m`.
+
+## push
+
+Pushes every active (non-merged, non-queued) branch in one multi-ref push with per-branch
+`--force-with-lease`.
+
+**Not atomic.** Some branches may update while another is rejected. A rejection means that branch
+moved on the remote; fix that branch and rerun — rerunning is safe and skips what already landed.
+
+`push` never creates or updates pull requests. Use `submit` for that.
+
+## submit
+
+Pushes each active branch, then creates a PR for every branch that lacks one, basing it on the
+first non-merged ancestor, then links them into a Stack on GitHub.
+
+- **Not atomic.** Branches are pushed sequentially with per-branch `--force-with-lease`. If a later
+  push is rejected, earlier pushes and PR updates stand. Fix the rejection and rerun the same command.
+- **A fully merged stack cannot be extended.** When every PR in the current stack is already merged,
+  `submit` forks the remaining unmerged branches into a **new** stack rooted at the trunk and creates
+  it on GitHub, leaving the merged stack untouched.
+- **Title generation with `--auto`:** a branch with a single commit uses that commit's subject as
+  the title and its body as the PR body. A branch with multiple commits humanizes the branch name
+  (hyphens and underscores become spaces). There is no flag for a custom title or body; use
+  `gh pr edit` afterwards.
+- `--open` marks new _and existing_ PRs ready for review; without it new PRs are drafts.
+- Requires stacked PRs to be enabled on the repository. If not, `submit` exits **9** when
+  non-interactive (under a TTY it offers to create ordinary unstacked PRs instead).
+
+## link
+
+Creates or updates a stack on GitHub **without any local tracking state**. This is the path for
+branches managed by another tool or living in another worktree — see `troubleshooting.md`.
+
+- Arguments are given bottom to top. Each is a branch name or a PR number; a numeric argument is
+  tried as a PR number first and falls back to a branch name.
+- **A numeric first argument is treated as a stack number only when a stack with that number
+  exists.** In that case the remaining arguments are appended to the top of that stack and you do
+  not re-list its current PRs: `gh stack link 7 feature-c`. Arguments already in the stack are
+  skipped; arguments belonging to a different stack are rejected.
+- Branch arguments are pushed automatically (non-force, atomic). Missing PRs are created with
+  auto-generated titles and correctly chained bases; existing PRs with a wrong base are corrected.
+- Stack membership is **additive only** — `link` never removes a PR from a stack.
+
+## sync
+
+The routine command. Steps, in order:
+
+1. **Fetch** from the remote.
+2. **Reconcile with the GitHub stack.** PRs added to the stack on github.com are pulled down and
+   appended locally. On divergence, aborts when non-interactive (see `troubleshooting.md`).
+3. **Fast-forward the trunk.** Skipped when already current; warns when diverged.
+4. **Cascade rebase when needed.** This runs if the trunk moved, a stack branch was fast-forwarded
+   from its remote, or a branch no longer contains its expected parent. Merged PRs are handled
+   automatically. On conflict, **all branches are restored** to their pre-rebase state and the
+   command exits **3**.
+5. **Push** all active branches, atomically.
+6. **Refresh PR state** from GitHub.
+7. **Sync the stack object** — link open PRs into a stack, additively. Only when two or more PRs
+   exist. `sync` never opens PRs; that is `submit`.
+8. **Prune** local branches for merged PRs, only when `--prune` is passed in a non-interactive
+   environment.
+
+## rebase
+
+Pulls from the remote and cascade-rebases. Use it when `sync` reported a conflict or when you need
+to rebase only part of the stack.
+
+- `--upstack` rebases from the current branch to the top. This is what you run after editing a
+  lower layer.
+- `--downstack` rebases from the trunk to the current branch.
+- `--no-trunk` skips fetching and the trunk rebase entirely, aligning stack branches with each
+  other only.
+- `--continue` after staging resolutions; `--abort` restores every branch.
+- A merged PR is detected automatically and replayed with `--onto` against the correct target, so a
+  squash-merged parent does not produce spurious conflicts.
+- Starting a rebase while one is in progress exits **7**.
+
+## view
+
+- `--json` writes the machine-readable payload to stdout. Its schema is in `SKILL.md`.
+- Bare `view` opens a full-screen TUI when stdout is a TTY, and prints static text when piped.
+- `--short` prints a compact one-line-per-branch summary and never opens the TUI, but it is
+  formatted for humans; parse `--json` instead.
+- `view` refreshes PR state from GitHub as a side effect, best-effort — it does not fail when the
+  API is unreachable.
+
+## checkout
+
+Accepts a stack number, PR number, PR URL, or branch name.
+
+- A bare number resolves as a **stack number first**, then a PR number, then a branch name.
+- Stack numbers, PR numbers, and PR URLs fetch from GitHub, pull the branches down, and set the
+  stack up locally.
+- If a local stack already exists over those branches with a different composition, `checkout`
+  cannot be forced past it. Run `gh stack unstack --local` first, then retry.
+- `checkout` has no flags. It relies on `remote.pushDefault` when several remotes exist.
+
+## unstack
+
+Removes the stack **grouping** only. It never deletes pull requests or branches.
+
+- With no argument it targets the active stack — the one containing the current branch — removing
+  it on GitHub and locally.
+- With a stack number it works from anywhere in the repository, tracked locally or not, via the API.
+  Local tracking is also removed when present.
+- `--local` removes local tracking only and never contacts GitHub. Combining `--local` with a stack
+  number that is not tracked locally is an error.
+- An unknown stack number exits **2**.
+
+## merge
+
+- Scope with an argument: pass a PR number to merge that PR and every unmerged PR below it in the
+  stack, or pass a stack number to merge every unmerged PR in that stack.
+- **All-or-nothing.** If any PR in that exact merge set cannot be merged, none are, and the reason
+  is reported.
+- The method comes from `--squash`, `--rebase`, `--merge`, or `--merge-method <method>`. Without
+  one, the last-used method is reused.
+- Only basic PR state is checked before merging: open and not a draft. Bypassing merge requirements
+  is not supported for stacks.
+- **A merge queue on the base branch overrides everything.** The stack is added to the queue rather
+  than merged; the queue chooses the method and any method flag you passed is ignored with a
+  warning. Queued PRs are submitted together but land as the queue processes them, so they may merge
+  in separate groups rather than all at once.
+- `gh pr merge` cannot merge a stack. Always use `gh stack merge`.
+
+## Navigation
+
+`up`, `down`, `top`, `bottom`, and `trunk` are always non-interactive. `up` and `down` accept a
+count (`gh stack up 3`). Movement clamps at the stack bounds, and merged branches are skipped when
+navigating from an active branch, so `bottom` lands on the lowest _unmerged_ branch.
+
+`gh stack switch` is a selection menu with no non-interactive path. Use the commands above instead.

package/.claude/skills/gh-stack/references/stack-design.md

@@ -0,0 +1,97 @@
+# Designing a stack
+
+How to decide what goes in each layer. Read this before running `gh stack init`.
+
+## Contents
+
+- [Plan the layers before writing code](#plan-the-layers-before-writing-code)
+- [Branch naming](#branch-naming)
+- [Staging changes deliberately](#staging-changes-deliberately)
+- [When to add a layer](#when-to-add-a-layer)
+- [One stack, one story](#one-stack-one-story)
+
+## Plan the layers before writing code
+
+A stack is a dependency chain. If code in one layer depends on code in another, the dependency must
+live in the same branch or a lower one. That constraint is much cheaper to satisfy by planning than
+by restructuring later, because there is no non-interactive in-place reorder — fixing the order
+means`unstack` and `init` again.
+
+Decide the layers first, then write code into them:
+
+```
+(main) <- todo-app/models <- todo-app/api <- todo-app/frontend <- todo-app/integration
+```
+
+- `todo-app/models` — shared types and schema
+- `todo-app/api` — routes that use the models
+- `todo-app/frontend` — components that call the routes
+- `todo-app/integration` — tests exercising the whole feature
+
+This is illustrative. Infer the stack topic and layer names from the actual task; do not reuse
+`todo-app` or these layer names literally.
+
+The failure mode to avoid is writing everything on one branch and trying to split it afterwards.
+If a task is large enough to warrant a stack, create the stack at the start.
+
+## Branch naming
+
+Prefer a shared topic prefix plus the layer's concern:
+`<topic>/<concern>` — for example, `billing/schema`, `billing/api`, `billing/ui`.
+This keeps related branches recognizable without using generic names that could belong to any
+stack. **User and repository branch naming conventions take precedence; follow them instead.**
+
+Names are used exactly as given — nothing is prepended or transformed, and slashes are kept, so
+`gh stack add refactor/foo` creates a branch literally named `refactor/foo`.
+
+If you pass `-m` without a branch name, the name is generated from the commit message in
+date-and-slug form (for example `03-24-add_api_routes`). Prefer naming the branch yourself.
+
+## Staging changes deliberately
+
+Use `git add` and `git commit` directly rather than the `add -Am` shortcut. The point is control
+over which changes land in which branch. With several modified files in the working tree, stage the
+subset that belongs to the current layer, commit it, then create the next branch and stage the rest
+there:
+
+```bash
+git add internal/models/user.go internal/models/session.go
+git commit -m "Add user and session models"
+
+gh stack add api-routes
+git add internal/api/routes.go internal/api/handlers.go
+git commit -m "Add user API routes"
+```
+
+Multiple commits per branch are fine. What matters is that every commit in a branch serves the same
+concern, and that a change belonging to a different concern goes in a different branch.
+
+Note that `gh stack add <branch>` without `-Am` does not touch the working tree, so uncommitted
+changes carry over to the new branch. Commit or stash first if you want the new layer to start clean.
+
+## When to add a layer
+
+Add a branch when you start a **different concern that depends on what you have built so far**.
+Signals:
+
+- Moving from backend to frontend, or from core logic to tests or documentation
+- The next changes have a different reviewer audience
+- The current branch's diff is already large enough to review on its own
+
+A layer that cannot be described in one sentence is usually two layers.
+
+## One stack, one story
+
+A stack should read as a coherent progression: a reviewer walks the PRs bottom to top and sees the
+feature being built.
+
+**Use a single stack** when every branch serves the same feature or project, even if the layers span
+different concerns.
+
+**Start a separate stack** for unrelated work — a different feature, an unrelated bug fix, an
+independent refactor. Do not mix efforts into one stack just because you happened to work on both.
+Use `gh stack init` for the new effort, or `gh stack checkout <target>` to move between existing
+stacks.
+
+A trivial incidental fix can ride along in the current stack. Once it grows into its own project, it
+deserves its own stack.